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 version

Ubuntu / 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
本地部署验收结果:sub2api、PostgreSQL 和 Redis 均为 running、healthy,健康接口返回 200

图 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. 登录管理员并完成内部设置

  1. 打开企业自己的 HTTPS 域名。
  2. 使用 .env 中的管理员邮箱和密码登录。
  3. 确认当前身份为管理员,保存凭据到企业密码管理器。
  4. 在系统设置中关闭不需要的“开放注册”,由管理员统一创建员工。
  5. 核对默认用户余额、默认并发和默认授权;初始预算由管理员按员工分配。
  6. 如需邮件找回密码,再配置 SMTP;关闭注册不等于关闭员工正常登录。
sub2api 管理员后台的通用设置:右上角管理员身份、左侧用户管理入口和中部 API 端点地址字段

图 S02:管理员登录后的后台示例。右上角“管理员”用于核对身份,左侧“用户管理”是后续创建员工账号的入口。查看清晰原图。

企业域名请在浏览器地址栏核对,例如 https://ai.example.com。本图未包含地址栏;“API 端点地址”中的 https://api.example.com 是输入提示,留空时使用当前站点地址。需要单独指定 API 地址时,填写企业实际地址。

系统设置的安全与认证页面,注册设置中的开放注册开关处于灰色关闭状态

图 S03:进入“系统设置 → 安全与认证 → 注册设置”,关闭“开放注册”右侧开关;图中灰色状态表示已关闭。默认余额、并发和授权还需在“用户默认值”等相应设置中单独核对。查看清晰原图。

通用设置中的“Backend 模式”会限制普通用户登录。企业需要员工登录个人账号时,保持该模式关闭,使用“开放注册”开关控制是否允许自行注册。

以上截图来自 sub2api v0.2.19,本文配置参考 v0.2.21,菜单以实际部署版本为准。

本页完成后,企业域名应能通过 HTTPS 访问,容器健康,管理员能登录。下一步:接入 RootFlowAI。返回企业团队接入总览。