Files
agent/docs/DEPLOY.md
T
kicer f84afe4246 部署:合并为单网络 + 新增 /mcp-uploads 公网只读中转(对外只开一个端口)
- docker-compose: 删掉 agent-internal,core/executor/init 全部只挂 my-app-network
  (executor 需要按容器名访问 mcp,两个网络已无隔离意义)
- docker-compose: 新增 MCP_UPLOADS_URL=http://mcp_video_gen:3001 开关中转路由
- routes/mcp-uploads.js(新): GET/HEAD /mcp-uploads/uploads/<file> → video_gen 只读监听
  挂在 auth.middleware 之前(智谱拉图不带凭据);只转 GET/HEAD,写路径不经公网;
  文件名白名单挡目录穿越;上游不可用回 502
- server.js: 装配上述路由
- 文档: DEPLOY.md 新增 4.1「图片中转」、ARCHITECTURE.md 补反向入站链路与单网络约束
- 已用一次性 harness 验证 15 项(含 POST/PUT/DELETE 一律 405、/mcp-uploads/upload 404、
  穿越文件名 400、上游只收到 GET/HEAD)
2026-09-15 19:40:34 +08:00

6.0 KiB
Raw Blame History

部署说明(Docker,IP:端口直连,无 nginx-proxy)

配置与编排文件都放在仓库顶层,方便直接调整:

宿主机路径 容器内路径 说明
./docker-compose.yml — 编排(构建 ./app,把容器 8080 映射到宿主机 8090)
./config.yml /app/config.yml 运行配置(AGENT_CONFIG 指向它;含密钥,已被 .gitignore 忽略)
./tasks/ /workspace/tasks 任务目录:AI 的文件工作区(与 executor 必须同路径)
./data/ /workspace/data 数据目录 + SQLite(.agent.db)
./skills/ /workspace/skills 技能目录:所有任务/会话共享
./.env — 编排变量(EXECUTOR_TOKEN / AGENT_PORT),已被 .gitignore 忽略

本仓库不含 config.yml 与 .env,需自行创建(见第 2 步)。

1. 网络(自动创建,无需手动)

agent-core 与 mcp 仓库的服务共用网络 my-app-network:agent 按容器名访问 MCP (如 http://mcp_web_search:3000/)。该网络由本仓库的 compose 创建(固定名字,不带项目名前缀), mcp 侧声明为 external 直接加入。

所以全新机器上有先后顺序:先起 agent(创建网络),再起 mcp(mcp 单独先起会因为网络不存在而报错)。

# 1) 先 agent,创建网络
docker compose up -d --build

# 2) 再 mcp
cd ../mcp && docker compose up -d --build

拆的时候反着来:先 down mcp,再 down agent。否则 agent 侧会报 network my-app-network has active endpoints(容器照删、网络留下,重新 up 就恢复,不损数据)。

2. 准备配置

cp app/config.example.yml config.yml
cp .env.example .env
vi .env         # 填 EXECUTOR_TOKEN,生成:openssl rand -hex 32
vi config.yml

config.yml 至少改这几处。容器内必须写绝对路径——core 与 executor 靠同一份 /workspace/tasks 看到彼此的产物,留成示例里的相对路径(./data/tasks)会解析到 /app/data/tasks,命令会因为不在 executor 白名单里而失败:

platforms: ...                       # 模型池:每个平台 url + keys.api_key
workspace_root: /workspace/tasks     # 不能留示例里的 ./data/tasks
data_root: /workspace/data           # SQLite 与 prompt dump 落在这个挂载卷里
skills:
  skills_root: /workspace/skills
auth:                                # 建议启用,否则谁都能访问
  secret: "换一个随机串"
  users:
    - user: admin
      password: "换一个密码"
mcp_servers:                         # 无域名时按容器名访问(模板已写好,按需启用)
  - name: web-search
    url: "http://mcp_web_search:3000/"

⚠️ 必须先有 config.yml 再 up:compose 挂载的是 ./config.yml:/app/config.yml, 文件不存在时 Docker 会在宿主机建一个同名目录,容器起来会读不到配置。

3. 构建并启动

# 在仓库顶层(含 docker-compose.yml 的位置)执行
docker compose up -d --build
docker compose logs -f agent-core    # 看到 "Agent server listening on 8080" 即成功

首次启动会先跑一次 agent-executor-init(把技能依赖落到宿主机 ./skills),跑完自动退出, 属正常现象。

4. 访问

浏览器打开 http://<服务器IP>:8090(端口可用 .env 里的 AGENT_PORT 改)。 登录用第 2 步 auth.users 里配的账号。

对外只需要放行这一个端口:agent-executor(9000)和 mcp 的三个服务都只在 my-app-network 内网,没有映射到宿主机(需要从宿主机 curl 调试时,去 mcp 仓库的 docker-compose.yml 里临时 把对应服务的 ports 两行取消注释)。

4.1 图片中转(只有图生视频会用到)

智谱服务器生成视频前要回来拉参考图,它不带 cookie、不带 Authorization,必须公网匿名可达。 而 video_gen 不该为此占一个公网端口(那样它的 POST /upload 也会一起暴露),所以由 core 代拉:

智谱  ──匿名 GET──►  http://<服务器IP>:8090/mcp-uploads/uploads/<随机文件名>
                          │  core 只转发 GET/HEAD
                          ▼
                     mcp_video_gen:3001   ← video_gen 的只读监听(那边压根没有 /upload)
  • AI 上传图片走的是内网 http://mcp_video_gen:3000/upload,写路径从不经过公网。
  • core 侧由 MCP_UPLOADS_URL=http://mcp_video_gen:3001 开启这条中转(compose 已配好); 留空则 /mcp-uploads/* 这条路由不存在。
  • mcp 侧必须把 PUBLIC_BASE_URL 设成 http://<服务器IP>:<AGENT_PORT>/mcp-uploads, 否则返回给智谱的地址不对,图生视频会失败(video_gen 启动日志会打印两个实际生效的地址,便于核对)。
  • 这条路径匿名可读:内容不可枚举(文件名是 randomUUID)、24h 后自动删除、只读不能写。

5. 没有 HTTPS 的影响(可忽略,仅记录)

HTTP 直连时浏览器不认为这是"安全上下文",以下能力自动降级,不影响主流程:

  • PWA / Service Worker 不注册(http://IP 不是 secure context),离线缓存与「添加到主屏」不可用。
  • 复制按钮的 navigator.clipboard 不可用,前端自动回退到旧 API。
  • 登录 cookie 本身没带 Secure 标志,HTTP 下正常签发与携带(auth.js 用的是 HttpOnly + SameSite=Lax)。

日后若加回 nginx / HTTPS 反代,注意 SSE 必须关代理缓冲,否则流式输出会被攒住不发:

location / {
    proxy_pass http://agent-core:8080;   # 或宿主机 IP:8090
    proxy_http_version 1.1;
    proxy_buffering off;                 # SSE 关键
    proxy_read_timeout 3600s;
}

6. 升级流程

git pull
docker compose up -d --build    # 仓库顶层执行

数据库与任务目录都在 bind 挂载的 ./data、./tasks 内,升级不丢数据。进程重启时, 原 active 会话会自动退回排队队列,待模型空闲后继续。