From 906e502b62a061df4ef8248e6f12dfde27133dd3 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 15 Sep 2026 17:54:42 +0800 Subject: [PATCH] =?UTF-8?q?=E9=83=A8=E7=BD=B2=EF=BC=9A=E6=94=B9=E4=B8=BA?= =?UTF-8?q?=20IP:=E7=AB=AF=E5=8F=A3=E7=9B=B4=E8=BF=9E=EF=BC=88=E6=97=A0=20?= =?UTF-8?q?nginx-proxy=EF=BC=89=EF=BC=8C=E5=90=8C=E6=AD=A5=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E6=A8=A1=E6=9D=BF=E4=B8=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docker-compose: expose 8080 → ports(AGENT_PORT 可覆盖宿主端口,默认 8080),去掉 VIRTUAL_HOST/VIRTUAL_PORT/CERT_NAME - config.example.yml: mcp_servers 改用容器名访问(http://mcp_web_search:3000/),去掉 nginx Basic 鉴权头 - docs/DEPLOY.md: 重写为 IP:端口直连;补外部网络创建、config.yml 必须用容器内绝对路径(否则 executor 拒绝 cwd)、HTTP 下 PWA/剪贴板降级说明 - README.md / docs/ARCHITECTURE.md: 同步对外暴露方式与架构图 --- .env.example | 3 ++ README.md | 18 +++---- app/config.example.yml | 17 +++++-- docker-compose.yml | 11 +++-- docs/ARCHITECTURE.md | 14 +++--- docs/DEPLOY.md | 107 +++++++++++++++++++++++++++++------------ 6 files changed, 115 insertions(+), 55 deletions(-) diff --git a/.env.example b/.env.example index 8c5c97d..549f90f 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,6 @@ # 复制为 .env 并填入真实值(.env 已在 .gitignore,不会被提交)。 # 生成 token:openssl rand -hex 32 EXECUTOR_TOKEN=change-me-openssl-rand-hex-32 + +# 选填:agent-core 在宿主机上的端口(默认 8080),改这里就不用改 docker-compose.yml。 +# AGENT_PORT=8080 diff --git a/README.md b/README.md index bdcf741..9cfa55f 100644 --- a/README.md +++ b/README.md @@ -781,17 +781,15 @@ services: agent: build: ./app restart: unless-stopped - expose: - - "8080" # 仅内网暴露,由 nginx-proxy 对外 + ports: + - "${AGENT_PORT:-8080}:8080" # 直接映射宿主机端口,IP:端口 访问 volumes: - - ./data:/workspace/tasks # 持久化:任务目录 + SQLite - - ./config.yml:/app/config.yml:ro + - ./tasks:/workspace/tasks # 持久化:任务目录 + - ./data:/workspace/data # 持久化:数据目录 + SQLite + - ./config.yml:/app/config.yml environment: - PORT=8080 - AGENT_CONFIG=/app/config.yml - - VIRTUAL_HOST=agent.ai.foresh.com - - VIRTUAL_PORT=8080 - - CERT_NAME=default networks: - my-app-network @@ -800,9 +798,11 @@ networks: external: true ``` -### 13.2 nginx-proxy 对外暴露 +### 13.2 对外暴露(IP:端口) -前置的 nginx-proxy 需与业务容器共用外部网络 `my-app-network`。compose 通过 `VIRTUAL_HOST`/`VIRTUAL_PORT`/`CERT_NAME` 接入;域名 `agent.ai.foresh.com` 的 DNS 指向 nginx-proxy 所在宿主机。认证用应用内置的多用户登录(`config.yml` 的 `auth.users`,登录页 `/login`),nginx 层不再配 htpasswd;多用户共享同一任务库,不做任务隔离;SSE 需关代理缓冲(`proxy_buffering off`),见 `docs/DEPLOY.md`。 +无域名/反代时,compose 直接把容器 8080 映射到宿主机端口,浏览器访问 `http://<服务器IP>:8080`(端口可用 `.env` 的 `AGENT_PORT` 改)。外部网络 `my-app-network` 与 `mcp` 仓库的服务共用,需先创建一次(`docker network create my-app-network`):agent 按容器名访问 MCP,如 `http://mcp_web_search:3000/`。认证用应用内置的多用户登录(`config.yml` 的 `auth.users`,登录页 `/login`),多用户共享同一任务库,不做任务隔离。 + +HTTP 直连时浏览器不认为这是“安全上下文”:PWA/Service Worker 不注册、`navigator.clipboard` 降级(前端已有回退),登录 cookie 无 `Secure` 标志可正常工作。日后若加 HTTPS 反代,**SSE 需关代理缓冲**(`proxy_buffering off`),详见 `docs/DEPLOY.md`。 --- diff --git a/app/config.example.yml b/app/config.example.yml index 02e4f66..24a1f69 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -118,9 +118,20 @@ model_hold: # 追加到内置工具之后一起发给模型;调用经 tools/call 转发。headers 是任意请求头(如 Authorization)。 # enable 选填、默认 true;设为 false 时启动不加载该服务的工具(配置保留,改回 true 重启即恢复)。 # 服务不可用时只在启动日志告警,不影响其他服务与内置工具。 +# +# 无域名部署:agent-core 与 mcp 仓库的容器共用 my-app-network,这里直接写【容器名:容器内端口】, +# 别写宿主机映射端口。日后改回域名/反代时,换成对应 https 地址即可。 mcp_servers: - name: web-search # 选填,缺省取主机名首段 - url: "https://web-search.ai.foresh.com/" + url: "http://mcp_web_search:3000/" # web_search 无服务端鉴权,不需要 headers enable: true # 选填,默认 true;false 时启动不加载 - headers: - Authorization: "Basic a2ljZXI6USF3MmUzcjQ=" + # 智谱系服务:token 由客户端透传(每次请求都要带),值填你的智谱 API Key。 + # 路径带 /mcp(web_search 是根路径 /,image/video gen 是 /mcp)。 + # - name: image-gen + # url: "http://mcp_image_gen:3000/mcp" + # headers: + # Authorization: "Bearer <你的智谱 API Key>" + # - name: video-gen + # url: "http://mcp_video_gen:3000/mcp" + # headers: + # Authorization: "Bearer <你的智谱 API Key>" diff --git a/docker-compose.yml b/docker-compose.yml index f7295a5..bf0c30a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,8 +3,10 @@ services: build: ./app container_name: agent-core restart: unless-stopped - expose: - - "8080" # 仅内网暴露,由 nginx-proxy 对外 + ports: + # 无 nginx-proxy:直接把容器 8080 映射到宿主机端口,用 http://<服务器IP>: 访问。 + # 改端口:在仓库顶层 .env 里设 AGENT_PORT(默认 8080)。 + - "${AGENT_PORT:-8080}:8080" volumes: - ./tasks:/workspace/tasks # 持久化:任务目录 - ./skills:/workspace/skills # 技能目录:所有任务/会话共享同一份技能 @@ -14,9 +16,6 @@ services: environment: - PORT=8080 - AGENT_CONFIG=/app/config.yml - - VIRTUAL_HOST=agent.ai.foresh.com - - VIRTUAL_PORT=8080 - - CERT_NAME=default # 加入executor独立服务 - EXECUTOR_URL=http://agent-executor:9000 # 调用鉴权 token:两侧同一值。从 .env 读取(已 gitignore),不再硬编码进仓库; @@ -122,6 +121,8 @@ services: - agent-internal networks: + # 与 mcp 仓库共用:agent-core 按容器名访问 MCP 服务(如 http://mcp_web_search:3000/)。 + # 只需创建一次:docker network create my-app-network my-app-network: external: true agent-internal: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d5bef80..6402d73 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -72,7 +72,7 @@ agent/ │ └── smoke-test.js Executor 自身冒烟(/health / exec 流式 / 鉴权 / 取消) │ └── docs/ - ├── DEPLOY.md 部署(nginx-proxy + HTTPS) + ├── DEPLOY.md 部署(Docker,IP:端口直连) ├── v2-develop.md v2 移动端单聊视图开发说明 └── ARCHITECTURE.md ← 本文件 ``` @@ -84,18 +84,18 @@ agent/ ```mermaid graph LR Browser((移动端浏览器
WebView/APK)) - Nginx[nginx-proxy
agent.ai.foresh.com] - Core[agent-core
:8080 内网] + Core[agent-core
宿主机 8080] Exec[agent-executor
:9000 内网] + MCP[MCP 服务
my-app-network] LLM[LLM 池
OpenAI 兼容] Tasks[./tasks
任务目录 bind mount] Skills[./skills
技能目录 bind mount] DB[(SQLite
.agent.db)] - Browser -->|HTTPS + Cookie| Nginx - Nginx -->|proxy_buffering off| Core + Browser -->|HTTP + Cookie| Core Core -->|SSE /exec| Exec Core -->|POST /chat/completions| LLM + Core -->|tools/call| MCP Core <-->|读写| Tasks Exec <-->|读写| Tasks Core <-->|技能 + deps| Skills @@ -103,7 +103,7 @@ graph LR Core --> DB ``` -两个容器通过 `agent-internal` 内网 bridge 通信;外网只暴露 Core(经 nginx-proxy)。 +两个容器通过 `agent-internal` 内网 bridge 通信;外网只暴露 Core(宿主机端口映射)。 **关键约束**(改 compose 时务必保持): @@ -659,7 +659,7 @@ sequenceDiagram ## 15. 进一步阅读 - `README.md` —— 设计文档(API 设计、SQLite 表结构、任务目录结构、Agent 主循环伪代码、Zed 风格工具定义全集) -- `docs/DEPLOY.md` —— 部署(nginx-proxy + HTTPS + SSE 缓冲坑) +- `docs/DEPLOY.md` —— 部署(Docker,IP:端口直连;外部网络、配置绝对路径、SSE 缓冲坑) - `docs/v2-develop.md` —— v2 移动单聊视图 - `app/config.example.yml` —— 配置模板(每个字段的注释很全) - `app/server/templates/system-prompt.txt` —— AI system prompt 全文 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 5bac6b0..1e2b45b 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -1,59 +1,104 @@ -# 部署说明(Docker + nginx-proxy,域名 agent.ai.foresh.com) +# 部署说明(Docker,IP:端口直连,无 nginx-proxy) 配置与编排文件都放在**仓库顶层**,方便直接调整: | 宿主机路径 | 容器内路径 | 说明 | |---|---|---| -| `./docker-compose.yml` | — | 编排(构建 `./app`,仅内网 expose 8080) | +| `./docker-compose.yml` | — | 编排(构建 `./app`,把容器 8080 映射到宿主机端口) | | `./config.yml` | `/app/config.yml` | 运行配置(AGENT_CONFIG 指向它;含密钥,已被 .gitignore 忽略) | -| `./data/` | `/workspace/tasks` | 任务目录 + SQLite(`.agent.db` 在此目录内) | +| `./tasks/` | `/workspace/tasks` | 任务目录:AI 的文件工作区(与 executor 必须同路径) | +| `./data/` | `/workspace/data` | 数据目录 + SQLite(`.agent.db`) | +| `./skills/` | `/workspace/skills` | 技能目录:所有任务/会话共享 | +| `./.env` | — | 编排变量(`EXECUTOR_TOKEN` / `AGENT_PORT`),已被 .gitignore 忽略 | -## 1. 准备配置 +> 本仓库不含 `config.yml` 与 `.env`,需自行创建(见第 2 步)。 + +## 1. 创建外部网络(只需一次) + +`agent-core` 与 `mcp` 仓库的服务共用外部网络 `my-app-network`:agent 按容器名访问 MCP +(如 `http://mcp_web_search:3000/`)。两个 compose 都声明为 `external`,所以必须先建: + +```bash +docker network create my-app-network +``` + +`docker network ls` 可确认是否已存在(这台机器上跑过 nginx-proxy 的话可能已经存在,跳过即可)。 + +## 2. 准备配置 ```bash cp app/config.example.yml config.yml -vi config.yml # 至少改 models(每个模型独立 url/api_key) +cp .env.example .env +vi .env # 填 EXECUTOR_TOKEN,生成:openssl rand -hex 32 +vi config.yml ``` -> 容器内运行时 `workspace_root` 写 `/workspace/tasks`(docker-compose.yml 已把 `./data` 挂到这里)。 -> 本仓库 git 只跟踪示例 `app/config.example.yml`,真正的 `config.yml` 在顶层且被忽略,密钥不会进库。 +`config.yml` 至少改这几处。**容器内必须写绝对路径**——core 与 executor 靠同一份 +`/workspace/tasks` 看到彼此的产物,留成示例里的相对路径(`./data/tasks`)会解析到 +`/app/data/tasks`,命令会因为不在 executor 白名单里而失败: -## 2. 构建并启动 +```yaml +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. 构建并启动 ```bash # 在仓库顶层(含 docker-compose.yml 的位置)执行 docker compose up -d --build -docker compose logs -f # 看到 "Agent server listening on 8080" 即成功 +docker compose logs -f agent-core # 看到 "Agent server listening on 8080" 即成功 ``` -## 3. nginx-proxy 对外暴露(agent.ai.foresh.com) +首次启动会先跑一次 `agent-executor-init`(把技能依赖落到宿主机 `./skills`),跑完自动退出, +属正常现象。 -compose 已通过 `VIRTUAL_HOST` / `VIRTUAL_PORT` / `CERT_NAME` 接入 nginx-proxy: +## 4. 访问 -- 前置的 nginx-proxy 容器必须与业务容器共用同一个外部网络 `my-app-network`(compose 声明为 external),并监听 80/443。 -- 域名 `agent.ai.foresh.com` 的 DNS 指向 nginx-proxy 所在宿主机。 -- 若你的 nginx-proxy 未默认关闭代理缓冲,需额外配置 `proxy_buffering off`——**SSE 必须关缓冲**,否则流式输出会被攒住不发。可给 nginx-proxy 挂一个自定义 conf: - ``` - server { - listen 80; - server_name agent.ai.foresh.com; - location / { - proxy_pass http://agent:8080; - proxy_http_version 1.1; - proxy_buffering off; # SSE 关键 - proxy_read_timeout 3600s; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } - } - ``` -- 认证建议直接在 `config.yml` 配置多用户登录(`auth.users`,见 config.example.yml 注释):登录页 `/login`,会话 token 走 HttpOnly cookie。不建议再用 nginx-proxy 的 htpasswd basic auth:手机浏览器原生下载不会携带 Basic 认证头,会导致下载失败;cookie 则会自动携带。若迁移到内置登录,记得去掉 nginx 上对应的 htpasswd 配置。 +浏览器打开 **`http://<服务器IP>:8080`**(端口可用 `.env` 里的 `AGENT_PORT` 改)。 +登录用第 2 步 `auth.users` 里配的账号。 -## 4. 升级流程 +对外只需放行这一个端口:`agent-executor`(9000)只在 `agent-internal` 内网,没有映射到宿主机。 + +## 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:8080 + proxy_http_version 1.1; + proxy_buffering off; # SSE 关键 + proxy_read_timeout 3600s; +} +``` + +## 6. 升级流程 ```bash git pull docker compose up -d --build # 仓库顶层执行 ``` -数据库与任务目录都在 volume 内,升级不丢数据。进程重启时,原 active 会话会自动退回排队队列,待模型空闲后继续。 \ No newline at end of file +数据库与任务目录都在 bind 挂载的 `./data`、`./tasks` 内,升级不丢数据。进程重启时, +原 active 会话会自动退回排队队列,待模型空闲后继续。