9.3 KiB
部署说明(Docker,IP:端口直连,无 nginx-proxy)
配置与编排文件都放在仓库顶层,方便直接调整:
| 宿主机路径 | 容器内路径 | 说明 |
|---|---|---|
./docker-compose.yml |
— | 编排(构建 ./app,把容器 8090 映射到宿主机 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:
# 什么都不给也能跑:默认账号 admin/admin、无模型(platforms: [])
./scripts/init.sh
# 给几个变量
BIGMODEL_KEY=xxx DEEPSEEK_KEY=yyy ZHIPU_KEY=zzz PUBLIC_IP=1.2.3.4 AUTH_USER=me ./scripts/init.sh
| 输入变量(均可选) | 说明 |
|---|---|
BIGMODEL_KEY / DEEPSEEK_KEY / QWEN_KEY |
模型平台 key,填几个启用几个(0~3 个) |
ZHIPU_KEY |
image_task / video_task 用;留空则这两个服务 enable: false(工具不加载) |
AUTH_USER / AUTH_PASSWORD |
登录账号(默认 admin/admin,记得改) |
PUBLIC_IP / AGENT_PORT |
对外地址与端口,写进 public_link.base_url(PUBLIC_IP 空则尝试自动探测) |
AUTH_SECRET / EXECUTOR_TOKEN |
一般不用给:不给就自动生成,并存在 .env 里复用(所以重跑不会掉登录态) |
生成的 config.yml 只含 deploy 相关段:platforms / auth / mcp_servers / public_link;其余配置项
(路径、超时、model_profiles 等)走 server/config.js 的默认值,完整清单见 app/config.example.yml。
⚠️ config.yml 是生成物,不要再手改:每次生成都会把旧的备份成 config.yml.bak.<时间戳>。
要改配置请带环境变量重跑该脚本,或者不用脚本、按第 2 节手动维护。
本机现成的一键流程(仓库外):
/root/deploy.conf放变量 →/root/init_repos.sh(拉仓库 → 把变量 export 出去 → 调本脚本)。
1. 网络(自动创建,无需手动)
agent-core 与 mcp 仓库的服务共用网络 agent-mcp-net: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
拆的时候反着来:先
downmcp,再downagent。否则 agent 侧会报network agent-mcp-net has active endpoints(容器照删、网络留下,重新 up 就恢复,不损数据)。
2. 准备配置(手动方式)
不用 scripts/init.sh 时,自己建这两个文件:
cp app/config.example.yml config.yml
cp .env.example .env
vi .env # 填 EXECUTOR_TOKEN / WXBOT_TOKEN(或直接跑 scripts/init.sh 自动生成)
vi config.yml
app/config.example.yml 与 server/config.js 的默认值一一对应,容器内可直接用(路径默认
/workspace/tasks、/workspace/data)。config.yml 里至少要配:
platforms: ... # 模型池:每个平台 url + keys.api_key + models.id;可留空,启动后到设置页添加
auth: # 建议启用,否则谁都能访问
secret: "换一个随机串"
users:
- user: admin
password: "换一个密码"
mcp_servers: # 无域名时按容器名访问(模板已写好,按需启用)
- name: web_search
url: "http://mcp_web_search:3000/"
public_link.base_url只在需要给外部服务公网 URL(图生视频取参考图)时才配;纯 IP:端口部署 填"http://<服务器IP>:8090",容器 env 有VIRTUAL_HOST(nginx-proxy)时以它为准(见第 4.1 节)。
⚠️ 必须先有
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 8090" 即成功
首次启动会先跑一次 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 的三个服务都只在 agent-mcp-net
内网,没有映射到宿主机(需要从宿主机 curl 调试时,去 mcp 仓库的 docker-compose.yml 里临时
把对应服务的 ports 两行取消注释)。
4.1 公网临时链接(只有“把本地文件交给外部服务”时才用到)
场景:图生视频时,智谱服务器生成视频前要自己来拉参考图,它不带 cookie、不带 Authorization,
所以必须有一条公网匿名可达的 URL。做法是给一个不透明短 ID(app/server/public-files.js):
22 字符随机串,服务端内存表记着它对应哪个会话的哪个文件、什么时候过期。
AI 拿链接的姿势:直接调内置工具 mint_public_link(只传文件名),core 在进程内签好并把 URL 当
工具结果返回。没有任何额外的 HTTP 签发端口,也不存在“AI 的命令带不了凭据”这个问题:
mint_public_link({ path: "_cgi-bin_..._d92292d.jpg" })
→ http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn
返回的就是现成 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";不配则mint_public_link直接报错 (需要公网 URL 的那部分功能就用不了,例如 video_task 拉不到参考图)。 例外:容器 env 里配了VIRTUAL_HOST(nginx-proxy 域名 + HTTPS 那套)时,前缀自动用https://<域名>, 不用改config.yml(改也盖不住它)。 - 链接有效期
public_link.ttl_ms,默认 30 分钟;签完尽快用掉。 - 沙箱外的人要用上这条链接,得拿到那个 22 字符随机 ID(猜不出来,也不可能枚举),且过期即废。
- 这条路不搬字节:文件始终在它原本的位置,也不需要 video_task 参与上传/落盘。
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:8090; # 或宿主机 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 会话会自动退回排队队列,待模型空闲后继续。