Files
agent/docs/DEPLOY.md
T

182 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署说明(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`:
```bash
# 什么都不给也能跑:默认账号 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 单独先起会因为网络不存在而报错)。
```bash
# 1) 先 agent,创建网络
docker compose up -d --build
# 2) 再 mcp
cd ../mcp && docker compose up -d --build
```
> 拆的时候反着来:先 `down` mcp,再 `down` agent。否则 agent 侧会报
> `network agent-mcp-net has active endpoints`(容器照删、网络留下,重新 up 就恢复,不损数据)。
## 2. 准备配置(手动方式)
不用 `scripts/init.sh` 时,自己建这两个文件:
```bash
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` 里至少要配:
```yaml
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. 构建并启动
```bash
# 在仓库顶层(含 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. 升级流程
```bash
git pull
docker compose up -d --build # 仓库顶层执行
```
数据库与任务目录都在 bind 挂载的 `./data`、`./tasks` 内,升级不丢数据。进程重启时,
原 active 会话会自动退回排队队列,待模型空闲后继续。