Beaver/beaver_project
6
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: update external connector deployment flow

Browse Source
This commit is contained in:
steven_li
2026-06-05 17:27:05 +08:00
parent 2c5205b06e
commit e0bc6c55b0
12 changed files with 318 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
部署指南.md
View File

@ -6,6 +6,7 @@
- `authz-service`
- `deploy-control`
- `router-proxy`
- 可选的 `external-connector` sidecar
- 自动创建出来的 `app-instance`
目标结果：
@ -35,6 +36,7 @@
```bash
docker --version
docker compose version
docker ps
python3 --version
openssl version
@ -96,6 +98,20 @@ export BEAVER_USER_FILES_MAX_UPLOAD_BYTES=$((5 * 1024 * 1024 * 1024))
export BEAVER_OUTLOOK_MCP_URL=''
export BEAVER_OUTLOOK_MCP_SERVER_ID='outlook_mcp'
export EXTERNAL_CONNECTOR_BASE_URL='http://external-connector:8787'
export EXTERNAL_CONNECTOR_TOKEN="$(openssl rand -hex 32)"
export BEAVER_BRIDGE_TOKEN="$(openssl rand -hex 32)"
export EXTERNAL_CONNECTOR_PORT=8787
export CONNECTOR_PUBLIC_BASE_URL='http://127.0.0.1:8787'
export CONNECTOR_PROVIDER=fake
export CONNECTOR_COMMAND_TIMEOUT_SECONDS=120
export WEIXIN_CONNECT_COMMAND=''
export WEIXIN_STATUS_COMMAND=''
export WEIXIN_SEND_COMMAND=''
export FEISHU_CONNECT_COMMAND=''
export FEISHU_STATUS_COMMAND=''
export FEISHU_SEND_COMMAND=''
```
变量说明：
@ -115,6 +131,13 @@ export BEAVER_OUTLOOK_MCP_SERVER_ID='outlook_mcp'
| `BEAVER_USER_FILES_MAX_UPLOAD_BYTES` | 用户文件系统上传上限，默认 5GB；聊天附件和 workspace 上传仍保留当前小文件限制 |
| `BEAVER_OUTLOOK_MCP_URL` | 可选 Outlook MCP HTTP 地址 |
| `BEAVER_OUTLOOK_MCP_SERVER_ID` | Outlook MCP server id，默认 `outlook_mcp` |
| `EXTERNAL_CONNECTOR_BASE_URL` | app-instance 容器访问外部连接器 sidecar 的地址 |
| `EXTERNAL_CONNECTOR_TOKEN` | app-instance 调用 sidecar 管理 API 的 bearer token |
| `BEAVER_BRIDGE_TOKEN` | sidecar 回调 app-instance bridge API 的 bearer token |
| `EXTERNAL_CONNECTOR_PORT` | sidecar 映射到宿主机的调试端口，默认 `8787` |
| `CONNECTOR_PUBLIC_BASE_URL` | sidecar 对外展示自身回调或资源地址时使用的 URL |
| `CONNECTOR_PROVIDER` | sidecar provider；本机连通性测试用 `fake`，真实接入再改成 `weixin_ilink`、`feishu_bot` 或 `vendor_cli` |
| `WEIXIN_*_COMMAND` / `FEISHU_*_COMMAND` | `vendor_cli` 模式下调用厂商脚本的命令；`fake` 模式留空 |
如果接入外部正式 MinIO，不需要启动本地 `beaver-minio`。把上面的 MinIO 变量改成正式服务即可：
@ -212,6 +235,7 @@ docker build -t beaver/app-instance:latest app-instance
docker build -t beaver/authz-service:latest authz-service
docker build -t beaver/deploy-control:latest deploy-control
docker build -t beaver/auth-portal:latest auth-portal/src
docker compose -f docker-compose.external-connectors.yml build external-connector
```
如果某个镜像构建失败，先修构建错误，不要继续往下跑。
@ -258,7 +282,37 @@ http://alice.localhost:8088
http://alice.apps.example.com:8088
```
## 7. 启动 MinIO
## 7. 启动 external-connector sidecar（可选）
`external-connector` 用于微信、飞书/Lark 这类需要独立进程或厂商 SDK 的连接器。当前部署可以先用 `fake` provider 验证 sidecar、token、网络和 app-instance 回调链路；正式接入时再把 `CONNECTOR_PROVIDER` 和对应命令换成真实配置。
如果暂时不需要微信或飞书连接器，可以跳过本节。但建议至少在测试环境跑一次，确认部署变量没有断。
```bash
cd "$PROJECT_ROOT"
docker compose -f docker-compose.external-connectors.yml up -d external-connector
```
检查：
```bash
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' | grep external-connector
curl -sS -H "Authorization: Bearer $EXTERNAL_CONNECTOR_TOKEN" \
"http://127.0.0.1:${EXTERNAL_CONNECTOR_PORT}/connectors"
```
预期 `/connectors` 返回连接器列表，至少包含 `weixin` 和 `feishu`。如果报 `401`，检查 `EXTERNAL_CONNECTOR_TOKEN` 是否和容器环境变量一致。
多实例部署时不要依赖 `BEAVER_BRIDGE_BASE_URL=http://app-instance:8080` 这种固定兜底地址。`deploy-control` 通过 `create-instance.sh --network "$BEAVER_NET"` 创建实例时，会让每个 app-instance 默认带自己的回调地址：
```text
EXTERNAL_CONNECTOR_CALLBACK_BASE_URL=http://<app-instance-container-name>:8080
```
sidecar 会按每个连接 session 保存这个回调地址，入站消息才能回到正确的用户实例。
## 8. 启动 MinIO
MinIO 是用户文件系统的后端实现细节。用户和前端不会看到 bucket、access key 或 prefix；Beaver 只通过 `/api/user-files/*` 暴露个人智能体文件系统。
@ -293,7 +347,7 @@ example object: users/alice/uploads/report.pdf
用户文件上传由 Beaver 后端代理到 MinIO，不暴露 bucket、prefix 或凭据。当前默认允许最大 5GB 的用户文件上传，业务上限由 app-instance 后端环境变量 `BEAVER_USER_FILES_MAX_UPLOAD_BYTES` 控制；反向代理默认 `client_max_body_size` 已提高到 5GB。MinIO 本身支持大对象和 multipart 上传，但 agent 对超大文件的读取/处理能力仍需要按具体任务另行验证。
## 8. 启动 authz-service
## 9. 启动 authz-service
```bash
docker rm -f beaver-authz-service >/dev/null 2>&1 || true
@ -332,7 +386,7 @@ docker inspect beaver-authz-service --format '{{range .Config.Env}}{{println .}}
| egrep '^(AUTHZ_ISSUER|DEPLOY_API_BASE_URL|USER_FILES_MINIO_)='
```
## 9. 启动 deploy-control
## 10. 启动 deploy-control
`deploy-control` 会挂载 Docker socket，再创建新的 `app-instance` 容器。这里最容易错的是路径挂载：
@ -353,8 +407,10 @@ docker run -d \
-v /var/run/docker.sock:/var/run/docker.sock \
-v "$PROJECT_ROOT/app-instance:$PROJECT_ROOT/app-instance" \
-v "$PROJECT_ROOT/router-proxy:$PROJECT_ROOT/router-proxy" \
-v "$PROJECT_ROOT/skills:$PROJECT_ROOT/skills:ro" \
-e APP_INSTANCE_DIR="$PROJECT_ROOT/app-instance" \
-e ROUTER_PROXY_DIR="$PROJECT_ROOT/router-proxy" \
-e DEFAULT_INITIAL_SKILLS_DIR="$PROJECT_ROOT/skills" \
-e PROXY_CONTAINER_NAME="$BEAVER_PROXY_CONTAINER_NAME" \
-e PROXY_NETWORK_NAME="$BEAVER_NET" \
-e DEPLOY_CONTROL_API_TOKEN="$BEAVER_DEPLOY_TOKEN" \
@ -365,6 +421,9 @@ docker run -d \
-e DEFAULT_AUTHZ_OUTLOOK_MCP_URL="$BEAVER_OUTLOOK_MCP_URL" \
-e DEFAULT_OUTLOOK_MCP_SERVER_ID="$BEAVER_OUTLOOK_MCP_SERVER_ID" \
-e DEFAULT_USER_FILES_MAX_UPLOAD_BYTES="$BEAVER_USER_FILES_MAX_UPLOAD_BYTES" \
-e DEFAULT_EXTERNAL_CONNECTOR_BASE_URL="$EXTERNAL_CONNECTOR_BASE_URL" \
-e DEFAULT_EXTERNAL_CONNECTOR_TOKEN="$EXTERNAL_CONNECTOR_TOKEN" \
-e DEFAULT_BEAVER_BRIDGE_TOKEN="$BEAVER_BRIDGE_TOKEN" \
-e DEPLOY_PUBLIC_SCHEME="http" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="$BEAVER_BASE_DOMAIN" \
-e DEPLOY_PUBLIC_PORT="8088" \
@ -378,7 +437,11 @@ docker run -d \
`DEFAULT_AUTHZ_INTERNAL_TOKEN` 会写入新建 app-instance 的后端 runtime env，用于 app-instance 后端读取自己的 internal MinIO settings。它不会传给前端。
## 10. 启动 auth-portal
`DEFAULT_EXTERNAL_CONNECTOR_*` 会写入之后新创建的 app-instance 容器环境变量。改动这些变量后，要重启 `beaver-deploy-control` 并重新创建实例，或手工重建已有实例容器；仅重启 sidecar 不会更新已存在 app-instance 的环境变量。
`DEFAULT_INITIAL_SKILLS_DIR` 需要和 `skills/` 的只读挂载路径一致。否则新实例能启动，但 workspace 里不会自动种入初始 published skills。
## 11. 启动 auth-portal
```bash
docker rm -f beaver-auth-portal >/dev/null 2>&1 || true
@ -401,13 +464,15 @@ docker inspect beaver-auth-portal --format '{{range .Config.Env}}{{println .}}{{
| egrep '^(AUTHZ_API_BASE_URL|DEPLOY_API_BASE_URL)='
```
## 11. 健康检查
## 12. 健康检查
```bash
curl http://127.0.0.1:19090/healthz
curl http://127.0.0.1:8090/healthz
curl -I http://127.0.0.1:3081
curl -I http://127.0.0.1:9001
curl -sS -H "Authorization: Bearer $EXTERNAL_CONNECTOR_TOKEN" \
"http://127.0.0.1:${EXTERNAL_CONNECTOR_PORT}/connectors"
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
docker logs --tail=50 beaver-router-proxy
```
@ -419,8 +484,9 @@ docker logs --tail=50 beaver-router-proxy
- `beaver-deploy-control`
- `beaver-auth-portal`
- `beaver-router-proxy`
- `external-connector`（如果启用了连接器 sidecar）
## 12. 浏览器首次测试
## 13. 浏览器首次测试
打开：
@ -572,7 +638,7 @@ docker run --rm --network "$BEAVER_NET" --entrypoint /bin/sh minio/mc:latest -lc
curl -X DELETE "http://127.0.0.1:19090/backends/$BACKEND_ID/settings/minio"
```
## 13. 确认实例已创建
## 14. 确认实例已创建
```bash
cd "$PROJECT_ROOT/app-instance"
@ -590,7 +656,22 @@ docker ps --format 'table {{.Names}}\t{{.Status}}' | grep app-instance
- `public_url`
- `instance_host`
## 14. 只看 auth-portal 页面
确认新实例拿到了连接器环境变量：
```bash
INSTANCE_CONTAINER='<app-instance-container-name>'
docker inspect "$INSTANCE_CONTAINER" --format '{{range .Config.Env}}{{println .}}{{end}}' \
| egrep '^(EXTERNAL_CONNECTOR_BASE_URL|EXTERNAL_CONNECTOR_TOKEN|EXTERNAL_CONNECTOR_CALLBACK_BASE_URL|BEAVER_BRIDGE_TOKEN)='
```
其中 `EXTERNAL_CONNECTOR_CALLBACK_BASE_URL` 应该指向这个实例自己的容器名，例如：
```text
http://app-instance-alice:8080
```
## 15. 只看 auth-portal 页面
如果只想看 Portal 页面，不跑全链路：
@ -608,7 +689,7 @@ http://127.0.0.1:3081
注意：这只能看页面。注册、登录、创建实例仍依赖 `authz-service` 和 `deploy-control`。
## 15. 常用排错命令
## 16. 常用排错命令
```bash
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
@ -617,10 +698,13 @@ docker logs --tail=100 beaver-authz-service
docker logs --tail=100 beaver-deploy-control
docker logs --tail=100 beaver-auth-portal
docker logs --tail=100 beaver-router-proxy
docker logs --tail=100 external-connector
curl http://127.0.0.1:19090/healthz
curl http://127.0.0.1:8090/healthz
curl -I http://127.0.0.1:3081
curl -sS -H "Authorization: Bearer $EXTERNAL_CONNECTOR_TOKEN" \
"http://127.0.0.1:${EXTERNAL_CONNECTOR_PORT}/connectors"
```
实例创建失败时再看：
@ -639,11 +723,14 @@ docker inspect beaver-authz-service --format '{{range .Config.Env}}{{println .}}
docker inspect beaver-auth-portal --format '{{range .Config.Env}}{{println .}}{{end}}' \
| egrep '^(AUTHZ_API_BASE_URL|DEPLOY_API_BASE_URL)='
docker inspect beaver-deploy-control --format '{{range .Config.Env}}{{println .}}{{end}}' \
| egrep '^(DEFAULT_EXTERNAL_CONNECTOR_BASE_URL|DEFAULT_EXTERNAL_CONNECTOR_TOKEN|DEFAULT_BEAVER_BRIDGE_TOKEN|DEFAULT_INITIAL_SKILLS_DIR)='
```
它们都必须是完整 URL，不能是空字符串，也不能是裸 `host:port`。
## 16. 常见问题
## 17. 常见问题
### 注册页报 URL 缺少协议
@ -727,23 +814,60 @@ getent hosts alice.localhost
- `8088`
- `8090`
- `19090`
- `8787`（如果启用了 `external-connector`）
检查：
```bash
ss -ltnp | grep -E '3081|8088|8090|19090'
ss -ltnp | grep -E '3081|8088|8090|19090|8787'
```
## 17. 重新部署基础容器
### 连接器 sidecar 返回 401
只重建基础四个容器：
检查 `docker-compose.external-connectors.yml` 里 sidecar 使用的是 `CONNECTOR_API_TOKEN`，主部署变量名是 `EXTERNAL_CONNECTOR_TOKEN`：
```bash
docker inspect external-connector --format '{{range .Config.Env}}{{println .}}{{end}}' \
| egrep '^(CONNECTOR_API_TOKEN|BEAVER_BRIDGE_TOKEN|CONNECTOR_PROVIDER)='
```
请求 sidecar 管理 API 时必须使用：
```bash
curl -H "Authorization: Bearer $EXTERNAL_CONNECTOR_TOKEN" \
"http://127.0.0.1:${EXTERNAL_CONNECTOR_PORT}/connectors"
```
如果改过 token，需要重启 `external-connector`、`beaver-deploy-control`，并重新创建或重建目标 app-instance。
### 微信或飞书连接成功但消息回不到实例
优先检查目标 app-instance 的回调地址：
```bash
docker inspect "$INSTANCE_CONTAINER" --format '{{range .Config.Env}}{{println .}}{{end}}' \
| grep '^EXTERNAL_CONNECTOR_CALLBACK_BASE_URL='
```
多实例部署里它必须指向当前实例自己的容器名，例如：
```text
EXTERNAL_CONNECTOR_CALLBACK_BASE_URL=http://app-instance-alice:8080
```
如果它为空，通常是实例创建时没有传 `--network "$BEAVER_NET"`，或者旧实例是在连接器变量加入前创建的。重新创建实例，或用同样的实例数据目录手工重建容器。
## 18. 重新部署基础容器
只重建基础容器和可选 sidecar：
```bash
docker rm -f \
beaver-auth-portal \
beaver-authz-service \
beaver-deploy-control \
beaver-router-proxy 2>/dev/null || true
beaver-router-proxy \
external-connector 2>/dev/null || true
```
这不会自动删除实例数据。如果你还需要旧账号、旧实例或模型配置，不要删除 `runtime/` 目录。