部署文档

两种部署方式：Docker Compose 一键编排，或单独构建 Docker 镜像手动运行。下方按方式分 Tab 查看，环境变量与配置项总表见独立页面。

配置与环境变量不在本页启动依赖按「环境变量 → .env → 内置默认」解析，全部字段、环境变量名、默认值与进程归属见环境变量清单。本页只讲两种方式的构建与启动命令，不重复配置字段。

先理解这套部署

这套平台需要两个数据组件：PostgreSQL保存渠道、模型、账号和平台配置，Redis保存请求运行状态、限流和节点运行态。Compose 会自动创建并启动它们，不需要你先单独安装数据库。

平台本身由两个服务组成：ai-lubricant负责对外 API 和 Web 管理端，node-server负责节点连接。普通用户只需要访问 ai-lubricant；node-server 只应开放给节点和 ai-lubricant 访问。

第一次部署前

# 应用配置文件：复制模板后按环境变量清单填写
cp .env.example .env

# Compose 数据库账号：在项目根目录创建 .env
POSTGRES_USER=ai_lubricant
POSTGRES_PASSWORD=请改成强密码
POSTGRES_DATABASE=ai-lubricant

这里的三个值是 PostgreSQL 初始化账号：Compose 第一次创建数据库容器时使用它们。密码不是给文档看的示例密码，部署前必须替换为真实强密码；已有数据库卷不会因为修改它们而自动改密码。

本地启动也自动加载 .envpython main.py 与 python -m node_server 启动时会自动解析项目根 .env，无需 export。外部环境变量优先于 .env。

为什么推荐 Compose它把应用和依赖放进同一个网络，应用自动用 postgres、redis 这两个服务名连接数据库；你不需要手工填写容器 IP，也不需要分别启动 PostgreSQL、Redis、ai-lubricant 和 node-server。Compose 的 env_file: .env 会把所有应用变量注入 ai-lubricant 容器，environment: 里的覆盖优先于 env_file，因此容器内仍连 postgres/redis 服务名。

启动平台

# 不需要额外 export，直接启动
# 第一次启动会构建应用镜像
docker compose up -d --build

# 查看四个服务是否正常
docker compose ps

# 查看数据服务日志
docker compose logs -f ai-lubricant

启动完成后，打开 http://127.0.0.1:3006 访问数据服务；节点控制服务使用 :8003，不要把它当作 Web 页面访问入口。

初始化数据库

docker compose exec ai-lubricant python init_db.py

空库配置注意init_db.py 创建数据库和基础表，但不等价于完整业务配置向导。启动时还需 PostgreSQL 中存在有效的主配置 app_config['main']。看到「缺少必填主配置」不要反复重启，应先按现有环境导入主配置；导入前移除真实 API Key、渠道凭据和管理员密码。

可选 ClickHouse

export CLICKHOUSE_REQUEST_PAYLOAD_ENABLED=true
docker compose --profile clickhouse up -d

关闭 ClickHouse 时模型代理主链路仍可工作；请求大字段双写和依赖 ClickHouse 的对话存储不可用。捕获请求正文前必须完成隐私评估。

停止与备份

# 停止但保留卷
docker compose down

# 危险：-v 会删除数据库卷，除非已确认备份，否则不要执行
# docker compose down -v

# 逻辑备份 PostgreSQL
docker compose exec -T postgres \
  pg_dump -U ai_lubricant -d ai-lubricant -Fc > ai-lubricant.dump

适用场景

已有外部 PostgreSQL/Redis（如内网托管），或需要单独控制两个进程的运行。用根目录 Dockerfile 构建同一个镜像，再分别以 python main.py 和 python -m node_server 启动两个容器。

构建镜像

# python:3.11-slim + requirements.txt，EXPOSE 8001，CMD python main.py
docker build -t ai-lubricant-api .

启动数据服务

# 外部 PG/Redis 地址通过环境变量注入；.env 共享且允许控制服务回写密钥
docker run -d --name ai-lubricant \
  -p 8001:8001 \
  --env-file .env \
  -e POSTGRES_HOST=10.x.x.x -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=... -e POSTGRES_PASSWORD=... -e POSTGRES_DATABASE=ai-lubricant \
  -e REDIS_HOST=10.x.x.x -e REDIS_PORT=6379 \
  ai-lubricant-api

启动节点控制服务

# 同一镜像，override command 跑控制服务；监听 0.0.0.0:8003（h2c）
docker run -d --name ai-lubricant-node-server \
  -p 8003:8003 \
  --env-file .env \
  -e POSTGRES_HOST=10.x.x.x -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=... -e POSTGRES_PASSWORD=... -e POSTGRES_DATABASE=ai-lubricant \
  -e REDIS_HOST=10.x.x.x -e REDIS_PORT=6379 \
  ai-lubricant-api python -m node_server

两个容器必须读同一份 .envnode_control_token 是数据服务→控制服务的内部 Bearer，两边必须完全一致。用同一个 --env-file .env（或两边导出同一个 NODE_CONTROL_TOKEN 环境变量）即可。控制服务缺少 token/密钥时会回写 .env，因此自动生成场景需用可写的 .env。

前端

数据服务启动时找 user-frontend/dist/index.html 作为管理端 SPA，无产物时回退 static/docs-viewer.html 不影响 API。构建：cd user-frontend && pnpm install && pnpm build。完整 Web 平台还需把 /api、/admin、/v1、/agent、/mcp 等前缀反代到数据服务（支持 WebSocket 与 SSE）。

本页目录生产运维

生产运维清单

只公开 HTTPS 入口；PG、Redis、ClickHouse 和 8003 放内网或限制来源。
启用 API Key 鉴权，创建最小权限 key，并定期轮换。
为 PostgreSQL、Redis 持久化数据、.env/Secrets、节点主密钥制定备份与恢复演练。
应用升级前备份数据库；先在预发布环境运行，验证流式 API、管理端、MCP、WebSocket、节点连接。
保留前一版本镜像和前端 dist。回滚应用时要判断数据库变更是否向后兼容，不能只回滚容器。
数据服务日志默认写到项目 logs/ai-lubricant-YYYY-MM-DD.log，按日轮转并保留 30 天；生产环境同步到集中日志平台并控制访问权限。
切换控制服务：先停旧控制进程再启新进程，绝不让两个 Registry 同时对同一批节点下发命令。
不要把请求 payload 捕获当作默认选项。开启前评估隐私、密钥脱敏、保留期和访问审计。