caiyun / micro

v1.0.1 2026-10-15 01:13 UTC

Requires

• php: ^8.3
• ext-json: *
• guzzlehttp/guzzle: ^7.0
• illuminate/cache: ^13.0
• illuminate/console: ^13.0
• illuminate/contracts: ^13.0
• illuminate/http: ^13.0
• illuminate/log: ^13.0
• illuminate/support: ^13.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.29.3
• mockery/mockery: ^1.6
• orchestra/testbench: ^11.0
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^12.0

Suggests

• ext-zookeeper: Required when using the zookeeper microservice driver.

MIT

• 刘骏霖

• laravel
• zookeeper
• etcd
• Microservice
• consul
• polaris
• nacos
• service-discovery
• service-registry
• caiyun

Published on Packagist.org on 2026-10-15 01:13 UTC

README

适用于 PHP 8.3+、Laravel 13.x 的微服务基础设施包，提供可插拔的服务发现与服务注册：

• static：本地/测试用固定 endpoints
• nacos：Nacos Open API（发现、注册、注销、心跳）
• consul：Consul HTTP API（TTL Check 心跳）
• etcd：etcd v3 HTTP/JSON API（Lease 保活）
• zookeeper：ZooKeeper（需 ext-zookeeper，节点心跳时间戳）
• polaris：PolarisMesh / 北极星 SDK HTTP API（Discover / Register / Heartbeat）
• log：仅记录日志，便于本地调试

业务侧通过服务别名调用下游，例如 Micro::for('agent')->post(...)，无需关心实例 IP。

安装

composer require caiyun/micro

发布配置：

php artisan vendor:publish --provider="Caiyun\Micro\MicroServiceProvider" --tag=micro-config

使用 Zookeeper 驱动时需安装 PECL 扩展：

pecl install zookeeper

快速配置

MICRO_DRIVER=static
MICRO_LOAD_BALANCER=random
MICRO_CACHE_TTL=15

# 当前服务（可选，用于注册到注册中心）
MICRO_SERVICE_NAME=caiyun-oa
MICRO_SERVICE_IP=127.0.0.1
MICRO_SERVICE_PORT=8000
MICRO_AUTO_REGISTER=false

# 下游别名
AGENT_SERVICE_NAME=caiyun-ai-agent
AGENT_TIMEOUT=60

# Nacos
NACOS_SERVER=http://127.0.0.1:8848
NACOS_NAMESPACE=
NACOS_GROUP=DEFAULT_GROUP
NACOS_USERNAME=
NACOS_PASSWORD=

# Consul
CONSUL_SERVER=http://127.0.0.1:8500
CONSUL_TOKEN=
CONSUL_GROUP=DEFAULT_GROUP
CONSUL_CHECK_TTL=15

# etcd
ETCD_SERVER=http://127.0.0.1:2379
ETCD_GROUP=DEFAULT_GROUP
ETCD_KEY_PREFIX=/caiyun-micro/services
ETCD_LEASE_TTL=15

# Zookeeper
ZOOKEEPER_HOSTS=127.0.0.1:2181
ZOOKEEPER_GROUP=DEFAULT_GROUP
ZOOKEEPER_ROOT_PATH=/caiyun-micro/services
ZOOKEEPER_INSTANCE_TTL=30

# Polaris（北极星）
POLARIS_SERVER=http://127.0.0.1:8090
POLARIS_NAMESPACE=default
POLARIS_GROUP=DEFAULT_GROUP
POLARIS_TOKEN=
POLARIS_HEARTBEAT_TTL=5

将 MICRO_DRIVER 设为 nacos / consul / etcd / zookeeper / polaris 即可切换注册中心。

static 驱动请在 config/micro.php 中配置 endpoints：

'static' => [
    'driver' => 'static',
    'endpoints' => [
        'caiyun-ai-agent' => [env('AGENT_BASE_URL', 'http://127.0.0.1:8080')],
    ],
],

用法

服务发现 + HTTP 调用

use Caiyun\Micro\Facades\Micro;

$response = Micro::for('agent')->post('/v1/chat', [
    'message' => 'hello',
]);

手动发现

$instance = Micro::select('caiyun-ai-agent');
$instances = Micro::getInstances('caiyun-ai-agent');

服务注册 / 心跳 / 注销

php artisan micro:register
php artisan micro:heartbeat
php artisan micro:deregister

或代码中：

Micro::registerSelf();
Micro::heartbeatSelf();
Micro::deregisterSelf();

生产环境可将 MICRO_AUTO_REGISTER=true，并配合调度周期性执行 micro:heartbeat（临时实例 / TTL / Lease 需要心跳保活）。

建议在 routes/console.php 或 Scheduler 中：

Schedule::command('micro:heartbeat')->everyFiveSeconds();

负载均衡

MICRO_LOAD_BALANCER 支持：

• random（默认）
• round_robin
• weighted_random

扩展 Driver

use Caiyun\Micro\Facades\Micro;

Micro::extend('consul', function ($app, array $config) {
    return new App\Micro\ConsulDriver($config);
});

开发

composer install
composer pint:fix
composer phpstan
composer test

# 或一次性校验
composer check