JECloud AI 只看四件事：关键字段、.env 必填项、持久化卷、端口暴露原则。其它一律按默认。
3.1 关键字段速览
小匠服务端 = postgres + agent 两个 service，agent 自带前端 SPA，无需 nginx。
- 打开
docker-compose.dev.yml，认准两块：environment（走.env）和volumes - postgres 必改
POSTGRES_PASSWORD，并同步到 agent 的DB_PASSWORD - 生产用
image: jecloud/xj-agent:<版本>替换 dev 的build: .，并删./src挂载和--reload
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: aiagent
POSTGRES_USER: aiagent
POSTGRES_PASSWORD: aiagent # 生产必改
ports: ["5432:5432"] # 生产删掉这行
volumes: [postgres_data:/var/lib/postgresql/data]
healthcheck: ...
agent:
build: . # 生产换 image: jecloud/xj-agent:vX
ports: ["3001:3001"] # 生产改 127.0.0.1:3001:3001
volumes:
- ./src:/app/src # dev 热更新，生产删
- ./static:/app/static # 同上
depends_on:
postgres: { condition: service_healthy }
volumes:
postgres_data:注意： 这是 dev 配置（带
--reload和代码挂载）。生产用不可变镜像，详见 ADR2026-06-15-dev-hot-deploy-plan。
3.2 .env 必填项
所有变量统一放项目根 .env，不要写死在 yml 里。下面只列必填和强烈建议，其它默认即可。
| 变量名 | 含义 | 示例 |
|---|---|---|
JECLOUD_AGENT_MASTER_KEY | 主加密 key（Fernet urlsafe-base64），生产从密钥服务注入 | — |
DB_HOST | 容器内走容器名 | jecloud-ai-agent-postgres |
DB_PORT / DB_NAME | 与 postgres 一致 | 5432 / aiagent |
DB_USER / DB_PASSWORD | 与 POSTGRES_USER / POSTGRES_PASSWORD 一致 | aiagent / 强密码 |
PLATFORM_BASE_URL | JECloud 平台地址（鉴权 / 元模型） | http://localhost:8080 |
JECLOUD_ROOT（建议） | 运行时数据根目录 | /var/lib/jecloud |
DEEPSEEK_API_KEY（建议） | v0.1 演示用，生产走管理壳「模型管理」入库 | sk-xxxx |
注意： .env 绝不提交 git。仓库只提供
.env.example模板，真密钥用密码管理器或公司密钥服务保存。其它可选变量（LOG_LEVEL/RAG_ENABLED/MESSAGES_HISTORY_LIMIT等）见.env.example注释。
3.3 持久化卷
只有 1 个核心卷 postgres_data，删了 = 删用户所有数据。
| 卷 | 装什么 | 备份 |
|---|---|---|
postgres_data（命名卷） | 数据库全部数据：账号 / 会话 / 配置 / 审计 | 每天 pg_dump，见⑤章 |
./static（bind） | 前端 SPA + 上传目录 | 每天打包 |
./src（bind） | dev 热更新源码 | 生产删除 |
- 查看物理位置：
docker volume inspect <project>_postgres_data - 要持久化用户上传，新增命名卷挂到
/app/static/uploads
3.4 端口暴露原则
对外只暴露 agent，且只暴露给本机 nginx；postgres 永远不出容器。
- 生产 删掉 postgres 的
ports:，agent 走 docker 内部网络连jecloud-ai-agent-postgres:5432 - agent 改
"127.0.0.1:3001:3001"，外网经 nginx 反代进入（见反向代理 + HTTPS） - 不要图方便用
"0.0.0.0:3001:3001"直接上公网，HTTPS / WSS / 限流全靠 nginx
注意： 切忌把 5432 暴露公网。需要远程连库走 SSH 隧道或公司 VPN。
3.5 改完之后
三条命令收尾。改 .env 也要 up -d 重建，不是 restart。
docker compose -f docker-compose.dev.yml config # 检查语法
docker compose -f docker-compose.dev.yml up -d # 重建生效
docker compose -f docker-compose.dev.yml ps # 两个 Up + postgres healthy小贴士： 改 yml 前先备份：
cp docker-compose.dev.yml{,.bak}；建议提交内部 git 做版本管理。
提示： 生产还想加什么？日志限制（
logging.options.max-size）、资源限制（deploy.resources）、命名网络等属于优化项，按需在生产 compose 里加，FAQ 有模板。