ENTERPRISE DEPLOYMENT
部署你的企业网关
使用固定版本 Docker Compose 部署企业 sub2api,配置管理员、持久化密钥、Nginx 和 HTTPS,完成内部平台初始化。
本页使用 Linux + Docker Compose,将 sub2api、PostgreSQL 和 Redis 部署在同一台服务器,并通过 Nginx 提供 HTTPS 访问。完成后,你可以用企业域名登录管理员后台。
配置参考 sub2api v0.2.21。以下服务器命令在 Bash 中执行;Nginx 安装示例适用于 Ubuntu / Debian。已有 sub2api 的企业可以直接阅读接入 RootFlowAI。
1. 准备服务器和域名
开始前准备以下内容:
| 项目 | 要求 |
|---|---|
| Linux 服务器 | 具备 SSH 和 sudo 权限,磁盘空间可容纳数据库、日志及备份 |
| Docker | 已安装 Docker Engine 和 Compose 插件,参考 Docker 官方安装文档 |
| 企业域名 | 例如 ai.example.com,DNS 已指向服务器公网地址 |
| 入站访问 | 按企业网络策略开放 HTTPS;申请下述证书时需要外部能访问 80 端口 |
| 出站访问 | 能访问 GitHub、Docker 镜像仓库和 https://api.rootflowai.com |
| 管理人员 | 明确谁维护服务器、员工权限与备份 |
先在服务器执行:
docker --version
docker compose version
docker info
python3 --version
openssl versionUbuntu / Debian 如缺少下载或编辑所需工具,可先安装:
sudo apt-get update
sudo apt-get install -y curl ca-certificates openssl python3 nano如果当前用户没有 Docker 权限,请使用具备相应权限的管理账号。机器容量应根据同时请求数、上下文长度、日志保留和资源监控确定,员工总数不能直接换算为请求并发数。
2. 下载固定版本的部署文件
创建独立目录:
sudo mkdir -p /opt/company-ai
sudo chown "$(id -u):$(id -g)" /opt/company-ai
cd /opt/company-ai下载本教程对应提交的 Compose 和环境变量模板:
curl -fL https://raw.githubusercontent.com/Wei-Shaw/sub2api/10ba8f9b4dc2e6023d4a9879ab77b21841babd10/deploy/docker-compose.local.yml -o docker-compose.local.yml
curl -fL https://raw.githubusercontent.com/Wei-Shaw/sub2api/10ba8f9b4dc2e6023d4a9879ab77b21841babd10/deploy/.env.example -o .env.example
cp .env.example .env
chmod 600 .env
mkdir -p data postgres_data redis_data执行 nano docker-compose.local.yml 打开配置,把应用服务 sub2api 的镜像行改为下面的值。使用 nano 时,按 Ctrl+O、回车保存,再按 Ctrl+X 退出:
image: weishaw/sub2api:0.2.21@sha256:868c15f3c729af05896c94b3456d91a68bc81dce50c4d7b4557682df7ca92c13这里固定了应用版本和镜像摘要。GitHub release 名称带 v,这个 Docker 镜像标签使用 0.2.21;不要写成 v0.2.21,也不要保留 latest。数据库和 Redis 先沿用配套文件的版本,后续升级时分别评估。
3. 设置管理员和持久化密钥
执行 nano /opt/company-ai/.env 打开环境文件,找到并修改下列字段:
BIND_HOST=127.0.0.1
SERVER_PORT=8080
RUN_MODE=standard
TZ=Asia/Shanghai
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=替换为独立的管理员强密码
POSTGRES_PASSWORD=替换为独立随机值
REDIS_PASSWORD=替换为另一个独立随机值
JWT_SECRET=替换为另一个独立随机值
TOTP_ENCRYPTION_KEY=替换为另一个独立随机值以上内容是填写示例,不要原样保存。管理员邮箱应使用企业自己的邮箱;管理员密码建议至少 16 位,且符合该版本的 8–72 字节要求。
为数据库密码、Redis 密码、JWT 密钥和 TOTP 密钥分别执行一次以下命令,每次使用新生成的值:
openssl rand -hex 32这些值只保存到企业服务器和企业密码管理器。每个字段单独占一行,不要增加空格或把多个值放在同一行;使用模板已有字段,不要重复添加同名配置。管理员密码若含 $ 等字符,应按 Compose 的 .env 规则用单引号包裹,避免变量插值。
JWT_SECRET 和 TOTP_ENCRYPTION_KEY 应长期保留,不能在容器重启时重新生成。修改 .env 中的初始化管理员或数据库密码,不会自动修改数据库里已经存在的凭据。
本教程使用 standard 模式。simple 模式会跳过计费和余额校验,不适合作为员工预算控制的默认模式。
4. 启动并检查服务
仍在 /opt/company-ai 中执行:
docker compose -f docker-compose.local.yml config --quiet
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d
docker compose -f docker-compose.local.yml ps首次启动需要下载镜像并初始化数据库,请等待健康检查完成。查看应用启动日志:
docker compose -f docker-compose.local.yml logs --tail=100 sub2api
图 S01:本地实际部署的检查结果,按命令输出整理为便于阅读的验收图。三个服务均为 running / healthy,/health 返回 200。图中本地演示端口为 8091,本页服务器部署示例使用 8080。查看清晰原图。
配套 Compose 启用了 AUTO_SETUP=true,会在首次启动时创建管理员。这里使用 .env 中的管理员邮箱和密码登录,不需要再执行二进制安装的初始化向导。
检查本机应用响应:
curl -I http://127.0.0.1:8080此时应用只监听服务器回环地址。不要为了让员工访问,直接把数据库、Redis 或 8080 端口全部开放到公网。
5. 配置域名、反向代理和 HTTPS
下面以服务器没有该域名的既有 Nginx 配置为前提。已有反向代理的企业可在现有入口配置等效规则,避免覆盖正在使用的站点。
安装 Nginx 和证书工具:
sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx执行 sudo nano /etc/nginx/sites-available/company-ai 创建站点配置,将其中的 ai.example.com 替换为企业域名:
map $http_upgrade $company_ai_connection {
default upgrade;
'' close;
}
server {
listen 80;
server_name ai.example.com;
client_max_body_size 50m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $company_ai_connection;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 900s;
proxy_send_timeout 900s;
}
}启用站点并检查配置:
sudo ln -s /etc/nginx/sites-available/company-ai /etc/nginx/sites-enabled/company-ai
sudo nginx -t
sudo systemctl reload nginx确认 DNS 已生效,再为企业真实域名申请证书。下面的域名必须替换:
sudo certbot --nginx -d ai.example.com --redirect
sudo certbot renew --dry-run证书签发后,用浏览器打开企业的 HTTPS 域名。如果使用 CDN、负载均衡或多层代理,还需要按企业入口结构配置流式响应、WebSocket 和可信代理,避免缓冲或过早超时。
6. 登录管理员并完成内部设置
- 打开企业自己的 HTTPS 域名。
- 使用
.env中的管理员邮箱和密码登录。 - 确认当前身份为管理员,保存凭据到企业密码管理器。
- 在系统设置中关闭不需要的“开放注册”,由管理员统一创建员工。
- 核对默认用户余额、默认并发和默认授权;初始预算由管理员按员工分配。
- 如需邮件找回密码,再配置 SMTP;关闭注册不等于关闭员工正常登录。

图 S02:管理员登录后的后台示例。右上角“管理员”用于核对身份,左侧“用户管理”是后续创建员工账号的入口。查看清晰原图。
企业域名请在浏览器地址栏核对,例如 https://ai.example.com。本图未包含地址栏;“API 端点地址”中的 https://api.example.com 是输入提示,留空时使用当前站点地址。需要单独指定 API 地址时,填写企业实际地址。

图 S03:进入“系统设置 → 安全与认证 → 注册设置”,关闭“开放注册”右侧开关;图中灰色状态表示已关闭。默认余额、并发和授权还需在“用户默认值”等相应设置中单独核对。查看清晰原图。
通用设置中的“Backend 模式”会限制普通用户登录。企业需要员工登录个人账号时,保持该模式关闭,使用“开放注册”开关控制是否允许自行注册。
以上截图来自 sub2api v0.2.19,本文配置参考 v0.2.21,菜单以实际部署版本为准。
本页完成后,企业域名应能通过 HTTPS 访问,容器健康,管理员能登录。下一步:接入 RootFlowAI。返回企业团队接入总览。