首次部署

五步走完：拿镜像 → 建目录 → 写 compose → up -d → 浏览器跑向导。完事把 URL 发给业务用户即可。

2.1 拿镜像

有外网走 ACR，无外网走离线 tar。两个镜像都要：jecloud-ai-agent + postgres:16-alpine。

有外网：docker login ACR → docker pull <地址>:<版本>
无外网：拿 tar → docker load -i jecloud-ai-agent-<版本>.tar
docker images 确认两个镜像都在

小贴士： ACR 地址 / 离线包找 JECloud 销售支持要。

2.2 建部署目录

所有配置、数据卷都放一个目录下，方便备份迁移。

mkdir -p /opt/jecloud-ai/{data,uploads,pgdata,logs}
cd /opt/jecloud-ai

注意： 别放系统盘：数据库和上传会涨得很快，挂独立数据盘，预留 100 GB。

2.3 写 docker-compose.yml

在部署目录下新建 docker-compose.yml，复制下面这份，改掉密码和镜像版本即可。

services:
  postgres:
    image: postgres:16-alpine
    container_name: jecloud-ai-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: aiagent
      POSTGRES_USER: aiagent
      POSTGRES_PASSWORD: change-me-strong-password
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U aiagent"]
      interval: 5s
      timeout: 5s
      retries: 10

  agent:
    image: registry.cn-hangzhou.aliyuncs.com/jecloud-ai/agent:v1.0.0
    container_name: jecloud-ai-agent
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
      - ./logs:/app/logs

必改三项：

POSTGRES_PASSWORD 改成 16 位以上随机串，记到密码本
image tag 改成 docker images 看到的真实版本
端口冲突就把左边 3001 改掉，比如 8080:3001

注意： 大模型 / MCP / 业务平台不在 compose 配，留到 2.5 浏览器向导里写库。所以不要找 LLM_API_KEY 这类环境变量。字段细节见docker-compose 配置详解。

2.4 启动并验证

同目录跑 up -d，等两个容器都 healthy。

$ docker compose up -d
$ docker compose ps
NAME                    STATUS                   PORTS
jecloud-ai-agent        Up 2 minutes             0.0.0.0:3001->3001/tcp
jecloud-ai-postgres     Up 2 minutes (healthy)   5432/tcp

等 30 秒，让 postgres 起来、agent 跑迁移
docker compose ps 看两个都 running/healthy
docker compose logs -f agent 看到 Application startup complete 就 OK

提示： 起不来？看 docker compose logs postgres，多半是 pgdata/ 权限或端口冲突，详见日志查看与故障排查。

2.5 跑系统初始化向导

浏览器开 http://<部署机 IP>:3001，第一次访问自动跳「系统初始化」向导（已初始化会直接到登录页）。5 步约 2 分钟。

admin 账号：用户名、显示名、邮箱、密码（小匠后台管理员，不是业务账号）
业务平台：名称、编码、类型（jecloud / jepaas）、URL（用户公司原本就在用的 JECloud/JEPaaS 地址）
大模型：默认 DeepSeek，API Key 自己粘；也可换其他 OpenAI 兼容协议
MCP 工具：默认 http://localhost:7000/mcp（agent 自带，不用另起）
完成：核对摘要 → 「完成初始化」→ 跳 /admin/login

注意： 业务平台 URL 必须填对：是用户公司的 JECloud/JEPaaS 地址，不是 agent 自己。填错业务用户全部登录失败。

2.6 把入口发给用户

用 admin 账号登一下后台确认配置都在，然后把入口交付出去。

浏览器：把 http://<域名>:3001 发给用户（生产建议先做反向代理 + HTTPS）
桌面端：从销售支持渠道拿 exe/dmg，发给用户装上自动连这套服务端
告诉用户：登录用原本的 JECloud/JEPaaS 账号，不用另注册；配套发用户手册第一章

小贴士： 首次部署完成 ✓ 推荐接着做：① 反向代理 + HTTPS ② 每日备份 ③ 收藏日志排查。