Files
agent/docs/DEPLOY.md
T
kicer 3f4ab51ea5 公网临时链接改为不透明短 ID(/p/<22字符>),不再暴露文件名/会话名/签名
- public-files.js(新): 内存表 id → (会话, 相对路径, 过期时间);mint 顺手清过期项并兜底上限
- routes/public-files.js(新): GET /p/<id> 匿名取用(查表 → resolveInTask 复核 → sendDownload),未命中/过期一律 404
- routes/public-link.js: 不再签 HMAC,改为 mint 短 ID,返回 http://<IP>:8090/p/<id>(约 50 字符、纯 ASCII)
  动因:原 URL 把文件名写了两遍再挂 64 位签名,共 300+ 字符;它会被模型抄进工具参数、并长期留在会话历史每轮重发
- download-send.js(新): 从 files.js 抽出 sendDownload/downloadDisposition,供浏览器下载与公网取用共用
- server.js: /p 挂在 auth.middleware 之前(匿名可达);浏览器下载那套签名链接保持不动
- docs: DEPLOY.md 4.1 / ARCHITECTURE.md(文件树、路由表、约束)/ README.md 同步
2026-09-15 21:27:43 +08:00

9.4 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 / AUTH_SECRET),已被 .gitignore 忽略
./scripts/init.sh — 一键生成上面两个文件并起服务(见第 0 节)

config.yml 与 .env 推荐交给 scripts/init.sh 生成(见第 0 节);不想用脚本的话也可以自己建(见第 2 节)。

0. 一键生成配置并启动(推荐)

scripts/init.sh 只读环境变量(不依赖任何外部文件),生成 .env 与 config.yml, 然后按顺序起 agent → mcp:

# 什么都不给也能跑:用默认账号 admin/admin、自动探测公网 IP、无模型(platforms: [])
./scripts/init.sh

# 给几个变量
BIGMODEL_KEY=xxx DEEPSEEK_KEY=yyy PUBLIC_IP=1.2.3.4 ./scripts/init.sh

# 只生成 .env / config.yml,不起容器(不装 Docker 的机器也能用)
UP=0 ./scripts/init.sh

# mcp 仓库不在 ../mcp 时指定
MCP_DIR=/path/to/mcp ./scripts/init.sh
输入变量(均可选) 说明
BIGMODEL_KEY / DEEPSEEK_KEY / QWEN_KEY 模型平台 key,填几个启用几个(0~3 个)
ZHIPU_KEY image-gen / video-gen 用;留空则这两个服务 enable: false(工具不加载)
AUTH_USER / AUTH_PASSWORD 登录账号(默认 admin/admin,记得改)
PUBLIC_IP / AGENT_PORT 对外地址与端口(PUBLIC_IP 空则尝试自动探测)
LOG_LEVEL 日志级别(默认 debug;日常用 info)
MCP_DIR / UP mcp 仓库位置(默认 ../mcp)/ UP=0 只生成配置
AUTH_SECRET / EXECUTOR_TOKEN 一般不用给:不给就自动生成,并存在 .env 里复用(所以重跑不会掉登录态)

⚠️ config.yml 是生成物,不要再手改:每次生成都会把旧的备份成 config.yml.bak.<时间戳>。 要改配置请带环境变量重跑该脚本,或者不用脚本、按第 2 节手动维护。

本机现成的一键流程(仓库外):/root/deploy.conf 放变量 → /root/init_repos.sh(拉仓库 → 把变量 export 出去 → 调本脚本)。

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. 准备配置(手动方式)

不用 scripts/init.sh 时,自己建这两个文件:

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
public_link:                         # 需要给外部服务公网 URL 时才配(图生视频用);见第 4.1 节
  base_url: "http://<服务器IP>:8090"
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),跑完自动退出, 属正常现象。

镜像构建默认走腾讯云镜像源(apt / pip / npm),否则国内机器上 apt-get update 可以卡十几分钟。 境外构建或想换源:docker compose build --build-arg DEBIAN_MIRROR=deb.debian.org agent-executor (mcp 仓库同理,参数名是 NPM_REGISTRY)。腾讯云 CVM 上还可换成内网镜像 mirrors.tencentyun.com。

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, 所以必须有一条公网匿名可达的 URL。做法是给一个不透明短 ID(app/server/public-files.js): 22 字符随机串,服务端内存表记着它对应哪个会话的哪个文件、什么时候过期。

AI 拿链接的姿势:core 额外在内网监听一个不映射到宿主机的端口(PUBLIC_LINK_PORT,默认 8081), 上面只有一条签发接口。因为压根没 publish,外部连不上,所以它不需要任何凭据:

# AI 在 executor 沙箱里执行(路径就是它平时看到的那个绝对路径)
curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/_cgi-bin_..._d92292d.jpg"
# → http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn
#   stdout 就是现成 URL(约 50 字符、纯 ASCII),直接当 image_url 用
智谱  ──匿名 GET──►  /p/9fQ2mZ7xK4tR1vBn        (core :8090)
                          │  查内存表:未过期?→ 得到(会话, 相对路径)
                          ▼
                     ./tasks/<会话>/foo.png    ← 文件仍在原地,零拷贝

为什么不做成“带签名的 URL”:那样必须把会话名、文件名、过期时间、64 位签名全塞进 URL(数百字符、 满是 %XX)。而这条 URL 会被模型抄进工具参数、并且永久留在会话历史里每轮重发, 太长又难抄,还白烧 token。短 ID 把三个问题一次解决了。

  • 必须在 config.yml 配 public_link.base_url = "http://<服务器IP>:8090";不配则不启动签发端口, video_gen 的工具描述里也不会出现那条命令(它会退化成“请运维配 PUBLIC_LINK_URL”)。
  • 链接有效期 public_link.ttl_ms,默认 30 分钟;签完尽快用掉。
  • 沙箱外的人要用上这条链接,得拿到那个 22 字符随机 ID(猜不出来,也不可能枚举),且过期即废。
  • 这条路不搬字节:文件始终在它原本的位置,也不需要 video_gen 参与上传/落盘。

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 会话会自动退回排队队列,待模型空闲后继续。