部署
说明
目前的部署方式是编译产物 + 反向代理,可以选用 PM2 守护进程。也可以用仓库自带的 GitHub Actions 工作流和部署脚本,推送版本标签后自动部署到 Linux 服务器,见 GitHub Actions 自动部署。Docker 镜像和 docker-compose 方案会在以后的版本中提供。完整、权威的步骤见仓库的部署文档。
构建
服务器需要 Node.js 22(不低于 22.22.1)、pnpm 11(仓库固定 11.28.3)、MySQL(推荐 8.4;按代码推定最低 8.0.17,没有测试过)、Redis 7.0 及以上。在仓库根目录执行:
pnpm i --frozen-lockfile
pnpm -r build服务端产物在 apps/server/dist/,从 apps/server 目录启动(见启动);前端产物 apps/web/dist/ 是静态文件,交给反向代理。保留整个仓库目录,不要只复制 dist/main.js;数据库、上传目录和密钥另外备份。Windows 上的构建和启动命令见仓库,Windows 服务器部署还没有验证。
生产环境变量
普通配置写 apps/server/.env(NODE_ENV=production、库名、Redis 库号、TRUST_PROXY、CORS_ORIGIN、SWAGGER_ENABLED=false 等),账号和密钥只写 .env.local 或进程环境,.env 里连空值也不写。不要复制开发或测试环境的密钥,生产环境会拒绝带 not-for-production 标记的密钥。Redis 库号先确认空闲,不和开发、测试、演示共用;.env.local 设为 600。示例见仓库,各项含义见环境变量。
v1.15.0 起新增数据库连接池设置 DB_POOL_SIZE(默认 10)、DB_POOL_ACQUIRE_TIMEOUT_MS 和 DB_POOL_QUEUE_LIMIT,默认值与以前行为相同;拿不到连接的请求会返回 503 而不是一直等。.env 和 .env.local 同一个键写了不同值时,以 .env 为准,启动日志会给出一条警告(只列键名)。见仓库。
Redis 还有两项要求,都来自任务队列(把耗时的工作交给后台执行的功能):
maxmemory-policy(内存满时怎么处理)必须是noeviction,在redis.conf里设置;其他策略会在内存不足时删掉键,排队中的任务就丢了。应用启动时检查这一项,不符合时只记警告日志。- 应用的 Redis ACL 用户需要只读的
INFO命令(例如在持久 ACL 里加+info)。
见仓库的任务队列 · Redis 要求。
首次部署的数据初始化:
pnpm db:migrate # 先执行迁移
pnpm db:seed # 再写入种子数据先迁移,再写种子数据,升级版本时也按这个顺序,执行前先备份数据库、上传文件和密钥。迁移和种子只在发布时执行一次,不要写进启动命令,见仓库。
警告
生产环境不要用 db:reset,它会删除所有表。(NODE_ENV=production 时这个命令本身也会拒绝执行。)
上线前处理示例账号
db:seed 会创建请假示例用的 5 个 OA 示例账号(共用一个只打印一次的随机密码),正式上线前请停用或删除它们,或者移除请假示例,也不要公开 seed 的输出。
启动
必须先进入服务端目录再启动:
cd apps/server
node --env-file-if-exists=.env.local --env-file-if-exists=.env dist/main.js不要在仓库根直接执行 node apps/server/dist/main.js:翻译、迁移、生成模板和上传目录都按工作目录查找。
启动后检查 GET /api/health、登录、文件上传和私有文件下载、实时推送是否正常。
反向代理(nginx)
服务端只监听 127.0.0.1,由反向代理对外提供访问。需要配置这几个路径:
| 路径 | 转发到 | 说明 |
|---|---|---|
/ | apps/web/dist/ | SPA 页面,用 try_files $uri /index.html 处理前端路由 |
/api/ | http://127.0.0.1:3000 | 接口 |
/socket.io/ | http://127.0.0.1:3000 | WebSocket,需要设置 Upgrade 和 Connection 头 |
/files/ | 本地存储的 public/ 目录 | 公开文件(头像、公告图片)直链访问 |
/.well-known/oauth- 开头的路径 | http://127.0.0.1:3000 | 只在打开智能体接入并用 OAuth2 接入时需要,要放在拦截点路径的规则之前 |
X-Forwarded-For 用 $remote_addr 覆盖,不能追加,否则 IP 黑名单和限流可能被绕过;Host、X-Forwarded-Host、X-Forwarded-Proto 保留浏览器访问的地址和协议,否则密码登录、短信登录、刷新登录和 WebSocket 会被拒绝(控制台登录返回 403 A1007)。代理做不到这一点时,把控制台的地址(比如 https://qiwu.example.com)加进环境变量 CORS_ORIGIN。nginx 下发的 CSP 必须和 apps/web/csp.ts 完全一致,client_max_body_size 要覆盖上传上限,/files/ 只能指向上传目录的 public/。完整配置见仓库。
建议在 listen 443 ssl 之后加上 http2 on;(nginx 1.25.1 及以上):浏览器对同一主机最多只开 6 个 HTTP/1.1 连接,慢接口和导出会让同页其他请求排队,HTTP/2 没有这个限制;不支持的客户端自动回落,WebSocket 照常可用。
使用 PM2 守护进程(可选)
PM2 能在崩溃后自动重启、开机自启。它是 AGPL-3.0 协议,只在服务器上全局安装(npm install -g pm2),不加进项目依赖。仓库自带 scripts/deploy/ecosystem.config.cjs(cluster 模式,2 个 worker);先执行迁移和种子,再 pm2 start。安装位置、升级顺序和调整 worker 数见仓库。同一台机器上的 cluster 已满足多实例部署的大部分条件。
所有 pm2 命令都用应用用户执行,例如 sudo -u qiwu -H pm2 logs qiwu-server;在 root 下直接执行会另起一个看不到应用进程的 PM2。想把定时任务和队列放到单独的进程,设置 QW_PM2_WORKER_INSTANCES(默认 0,保持单个应用),会多出一个 worker 应用,详见仓库。
GitHub Actions 自动部署
仓库自带两个 GitHub Actions 工作流(写在 .github/workflows/ 里、由 GitHub 自动执行的一组步骤)和一套 Linux 部署脚本(scripts/deploy/),可以选用。推送到 main 或提交合并请求(PR)时运行完整检查(CI),检查拆成多个并行的作业(服务端测试和网页端到端测试各分 3 片同时跑),汇总作业 gate 在全部作业成功时才算通过;推送 vX.Y.Z 标签后,先确认这个提交的 CI(以 gate 为准)已经通过,再创建 GitHub Release,并经 SSH 部署到服务器。用在自己的仓库时,两个工作流里的仓库名要一起改。每个版本放在单独的目录里,切换时不停机;健康检查失败时自动切回上一版代码,数据库不回退,所以迁移要兼容上一版本。服务器下载源码时不带凭据,标签所在的仓库必须公开。
发布一个版本:在 CHANGELOG.md 写好 ## [1.2.0] 一节,推送到 main 并等 CI 通过,再在这个提交上打标签:
git tag -a v1.2.0 -m v1.2.0
git push origin v1.2.0细节见仓库:仓库设置、服务器布局、服务器准备、每次部署、边界。
使用 S3 存储时
在 系统管理 → 文件管理 → 存储配置 启用 S3 后,私有文件由浏览器直接从 S3 读取。所以要用 CSP_CONNECT_SRC 登记 S3 地址再构建前端,并让 nginx 下发同一份 CSP;存储桶配好 CORS(允许本站的 PUT、GET),给 staging/ 设生命周期规则;非标准端口登记 OUTBOUND_S3_PORTS。命令见仓库。
OAuth2 与单点登录
/sso 是前端路由,反向代理要把它回退到 index.html(上面的路径表已包含);TRUST_PROXY 要设成反向代理的地址,否则授权和令牌接口的按 IP 限流全算在代理一个 IP 上;生产环境的回调地址必须是 https://。见仓库和 OAuth2 接入指南。
打开或关闭多租户
多租户默认关闭。开关是 apps/server/.env 里的 APP_MULTI_TENANT(不是秘密),只在启动时读取,改完要重启全部实例才算切换完成。
- 新安装:可以一开始就设为
true,第一次pnpm db:migrate就会把数据库准备好。 - 已有数据库:分两次部署。第一次保持开关关闭,升级到新版本,确认全部实例都正常;第二次把开关改为
true,执行pnpm db:migrate,再重启全部实例。如果在同一次部署里既升级又打开开关,生产环境的服务会拒绝启动。打开前,先复核默认租户里哪些角色有平台菜单:打开后,这些角色仍能使用影响全部租户的平台页面。 - 关闭:改回
false并重启全部实例后,只有默认租户可用:其他租户的数据保留,但它们的用户无法登录,已登录的会话在下一次请求时结束。关闭前,先在 系统管理 → 租户管理 里停用不再服务的租户,否则以后再打开开关时,它们会立刻恢复可用。
打开后不能退回旧版本
打开过开关的数据库,不能再回到 1.1.0 以前的任何版本。旧版本的代码不按租户过滤数据。
租户可以绑定自己的域名,用户在这个域名上登录时不用填租户编码;DNS、nginx 的 server_name 和证书都要加上这些域名,CORS_ORIGIN 却只写平台自己的地址,不写租户的域名,见租户绑定域名。完整步骤见仓库的打开多租户开关、关闭多租户开关和多租户文档。
公众号模块
微信公众号模块默认关闭。开关是 apps/server/.env 里的 APP_WXOA(不是秘密),只在启动时读取,改完要重启全部实例。关闭时 /api/wxoa/*(包括回调地址)返回 404,不访问微信,侧栏里也看不到 公众号 分组。数据表不管开关如何都由迁移创建,所以打开时不需要另外迁移。
- 回调地址是
/api/wxoa/callback/<key>,必须能从公网访问,并且使用 80 端口(http)或 443 端口(https),这是微信的要求。反向代理按现有的/api/规则转发即可。 - 正式号要把服务器的出口 IP 加进公众平台的 IP 白名单,多个实例或经 NAT 出网时每个出口 IP 都要加。
TRUST_PROXY要设成实际反向代理的地址,否则回调的失败计数全算在代理一个 IP 上。
智能体接入(MCP)
MCP 智能体接入默认关闭。开关是 apps/server/.env 里的 APP_MCP(不是秘密),只在启动时读取,改完要重启全部实例。关闭时 /api/mcp、/.well-known/oauth-* 和 /api/mcp/* 管理接口都返回 404,侧栏里也看不到 MCP 工具、访问令牌 两页。数据表不管开关如何都由迁移创建,所以打开时不需要另外迁移。
- 智能体调用的
POST /api/mcp走现有的/api/转发,不用另配。 - 用 OAuth2 接入的客户端还要读两个发现文档:
/.well-known/oauth-protected-resource(以及它后面接/api/mcp的路径)和/.well-known/oauth-authorization-server。很多 nginx 配置用location ~ /\.拦截以点开头的路径,这时要在它之前单独把/.well-known/oauth-开头的路径转给服务端,仓库的 nginx 示例已经这样写了。只用个人访问令牌时可以不转发。 - 代理要保留客户端发来的
Host和协议:OAuth2 的资源地址按请求到达的域名计算(https://<域名>/api/mcp)。 - 端点按来源 IP 限流(每分钟 600 次),所以
TRUST_PROXY要设成实际反向代理的地址。 - 运行中要紧急停止,由超级管理员把参数
mcp.paused改成true,不需要重启。
见仓库的智能体接入(MCP)和 nginx 反向代理与 CSP。
智能助手
智能助手默认关闭。开关是 apps/server/.env 里的 APP_AGENT(不是秘密),只在启动时读取,改完要重启全部实例。关闭时 /api/agent/* 返回 404,不注册它的队列处理器,侧栏、角色授权树和租户套餐里也看不到 智能体 分组。数据表不管开关如何都由迁移创建,所以打开时不需要另外迁移。
- 不需要新的服务:对话在现有的 Redis 任务队列里执行(Redis 的要求见上文生产环境变量),进度经现有的 Socket.IO 推送。
- 出口防火墙要放行服务端访问所配置的模型服务(如
api.deepseek.com、dashscope.aliyuncs.com、api.moonshot.cn、open.bigmodel.cn、api.openai.com,或内网的 Ollama)、搜索服务(api.bochaai.com、api.tavily.com)、要读的公网网页和外部 MCP 服务器。联网读取和外部 MCP 直接连接,不经 HTTP 代理。 - 模型、搜索和外部 MCP 的密钥在后台的 智能体 → 智能体设置 页填写,用
APP_SECRET派生的密钥加密存库,不写进任何 env 文件;更换APP_SECRET后要重新填写。 - 运行中要紧急停止,由超级管理员把参数
agent.paused改成true,不需要重启;用量和并发由agent.limit.*参数限制。 ALLOW_PRIVATE_ENDPOINTS=true会同时放开联网读取和外部 MCP 的内网地址检查,生产环境保持false。
见仓库的后台智能体(智能助手)。
演示模式
公开演示站设 APP_DEMO_MODE=true,使用独立的库、Redis 库号和密钥。除登录、退出、标为已读等少数操作外,写操作一律返回 403,超级管理员也一样;OAuth2 授权和令牌接口也被拒绝,要演示单点登录请用非演示安装;智能体调用 POST /api/mcp 同样被拒绝;日志页面里访客的 IP 和浏览器信息脱敏显示。同时打开多租户时,还会创建两个示例租户,访客可以进入和退出租户。开关改回 false 不会让已公开的密码失效,正式环境请重新安装。放行清单见仓库安全文档,另见部署文档。
多实例部署
服务端可以运行多个实例,实时推送和限流经 Redis 共享。前提:Redis 7 及以上;同一部署的所有实例连同一个 MySQL 库和 Redis,REDIS_DB、REDIS_KEY_PREFIX、APP_SECRET 和程序版本都相同,不同部署用不同库号;所有实例的 APP_MULTI_TENANT 也要相同,切换时全部重启;本地文件放共享目录,跨机器建议用 S3。每个实例都运行全部队列的处理器,同一个任务只会被一个实例取走,加实例就加处理能力;任务可能执行不止一次,处理器要能安全地重复执行,见仓库。只用 WebSocket,不需要粘性会话;迁移和种子仍只在发布时执行一次。模板只在同一台机器上用两个进程测试过,完整条件和限制见仓库。
v1.15.0 起可以用 APP_ROLE(all / api / worker,默认 all)让不同进程分工:api 只处理请求,worker 跑定时任务和队列。至少要保留一个 all 或 worker 实例,否则定时任务和队列任务不再执行;用 PM2 时见上文。同一台机器上 QW_PM2_INSTANCES × DB_POOL_SIZE 要小于 MySQL 的 max_connections。见仓库。