使用 Docker Compose 部署
从源码构建 BOS API,手动管理私有配置、应用、MySQL 与 Redis,完成 HTTPS 和日常运维。
前置要求与部署方式
首次部署和后续源码更新统一执行 ./deploy/stack.sh up --source:缺少 deploy/stack.env 时自动生成配置,已存在时复用密码、密钥和自定义设置,再构建并启动服务,无需单独执行 init。命令在 bos-api 应用仓库执行,不在当前官网仓库执行,也不会自动拉取 Git。
本页面向 Linux 单机部署,默认由宿主机 Nginx 提供静态前端、Go 提供 API。up --source 自动创建缺失的静态目录,父目录不可写时调用 sudo;应用启动并发布成功后配置 Nginx,后续更新复用这些设置。已有数据的实例先核对备份、目标版本与原始配置。
| 项目 | 要求 |
|---|---|
| Docker | Docker Engine、Compose v2(支持 up --wait)和 Buildx;使用本机 Docker,当前用户须能执行 docker info。 |
| 命令行工具 | Git、Bash、OpenSSL 和 curl。以 root 或已有 Docker 权限的部署用户执行命令,并始终使用同一用户与 Docker daemon。 |
| 静态前端 | 默认 Nginx 模式需要宿主机 Nginx、Python 3.9+,以及部署用户可写、Nginx 可读的静态目录。 |
| 网络与资源 | 能访问源码仓库、所选镜像仓库、npm/pnpm 和 Go 模块源。预留源码编译、镜像及持久化数据所需的内存和磁盘空间。 |
| 默认端口 | 应用为 127.0.0.1:18080,MySQL 为 127.0.0.1:13306;Redis 不映射宿主机端口。启用公网 HTTPS 时另需 80 / 443。 |
docker info
docker compose version
docker buildx version
git --version
bash --version
openssl version
curl --version- 无需在宿主机安装 Go、Node.js、MySQL 或 Redis。选择 BOS_WEB_DELIVERY=go 可由应用提供前端,跳过静态发布与 Python 要求;Nginx 也可仅反向代理应用。
- Compose 项目名固定为 bosapi-stack。请勿与一键安装共用同一 Docker daemon 再创建第二套默认实例;复制目录不会隔离容器、端口或数据卷。
步骤一:获取源码
在目标服务器上克隆 BOS API 应用仓库。后续命令均在该应用仓库根目录执行;当前官网仓库 boss-api-protal 用于展示文档。
git clone https://github.com/secure-typex/bos-api.git bos-api
cd bos-api
git rev-parse HEAD保存输出的提交号,便于核对部署版本。仓库需要登录时,使用你已有的 Git 认证方式,不把访问令牌写进命令或文档。
- 生产部署可在初始化前切换到已审核的标签或提交。确保该版本包含本指南使用的 deploy/stack.sh、docker-compose.yml 和 backend/Dockerfile。
- 构建依赖完整的 frontend/、backend/ 及构建上下文,不要只下载 docker-compose.yml。仓库尚未公开时,公开下载地址可能返回 404。
步骤二:确认静态目录,可选编辑配置
默认配置使用 BOS_WEB_DELIVERY=nginx、BOS_WEB_ROOT=/var/www/bosapi。可直接执行下一步的 up --source:脚本先检查 Docker,再创建并检查缺失的静态目录,最后初始化配置并启动。新目录权限为 0755,父目录不可写时需 sudo 权限;已有目录及权限保持不变,不可写时须另行修复。脚本不安装或配置 Nginx。
静态目录必须是专用绝对路径,不能是文件系统根目录,也不能位于应用源码目录内或包含源码目录;该路径及其父目录不能是符号链接。start 和 publish-web 只检查现有目录,不负责创建;旧版脚本可能仍要求提前手动准备目录。
sudo install -d -o "$(id -un)" -g "$(id -gn)" -m 0755 /var/www/bosapiup --source 已会创建缺失目录,通常可跳过此命令。手动准备时,当前用户应为后续执行部署的用户。静态目录需位于应用源码目录之外,根目录及其父目录不能是符号链接,Nginx 需有读取和目录遍历权限。
./deploy/stack.sh init只有需要提前修改端口、管理员邮箱或前端模式时才需此步骤。init 仅生成或复用配置,不启动容器;当前脚本会在终端显示初始管理员邮箱和密码。up --source 已包含初始化逻辑,其完成提示仅显示凭证文件位置。
BOS_WEB_DELIVERY=nginx
BOS_WEB_ROOT=/var/www/bosapi
BOSAPI_BIND_IP=127.0.0.1
BOSAPI_PORT=18080
BOS_ADMIN_EMAIL=owner@example.com
TZ=Asia/Shanghai这是配置片段,不是覆盖整个文件的模板。用编辑器修改已有字段,保留全部密码和密钥。无需静态发布时将 BOS_WEB_DELIVERY 改为 go,即可省略静态目录准备。
- 已有完整配置时,up --source 复用原密码、密钥、数据挂载与前端模式,不会重置现有管理员账号。
- stack.sh 自动加载 deploy/stack.env。手动执行 Compose 命令时仍需 --env-file deploy/stack.env 和 -f deploy/docker-compose.yml,不要用 source 执行配置文件。
- 已有数据却丢失 stack.env 时,先恢复原配置和密钥,再执行 init 或 up。管理脚本不具备一键安装入口的旧卷保护检查,新密钥无法解密旧数据。
步骤三:构建并启动服务
首次部署和后续更新使用同一条命令。脚本检查 Docker,在 Nginx 模式下创建缺失的静态目录并检查权限,按需生成私有配置,构建前后端并等待服务健康,最后发布前端。所有命令在 bos-api 根目录执行。
| 命令 | 构建与更新行为 |
|---|---|
| ./deploy/stack.sh up --source | 构建当前源码;后端就绪后移除旧 deploy/image.env,后续默认使用源码模式。 |
| ./deploy/stack.sh up --image IMAGE_REFERENCE | 替换 IMAGE_REFERENCE 为目标版本标签或摘要。拉取镜像并解析为不可变本地镜像 ID,后端就绪后写入 deploy/image.env,不构建应用源码。 |
| ./deploy/stack.sh up | 存在 deploy/image.env 时复用固定镜像,不拉取也不构建;否则构建源码。上传新源码后应显式使用 --source。 |
| ./deploy/stack.sh start | 沿用现有模式和本机镜像启动,不构建源码或主动获取新版应用镜像。 |
./deploy/stack.sh up --source./deploy/stack.sh status- app 的 depends_on 会启动 MySQL 和 Redis,并等待它们健康后再启动应用。首次构建会下载依赖并编译前后端,启动时自动应用待执行的数据库迁移。
- --source 明确构建当前源码,即使该主机以前固定过镜像版本;脚本不会拉取 Git。更新前先上传或拉取目标源码。仅执行 start 或 docker compose pull 不会构建新代码。
- Nginx 模式会从健康应用镜像发布前端,并原子切换 /var/www/bosapi/current。日常更新无需手动复制前端或重载 Nginx;配置 Nginx 本身时才需校验和重载。
- 如果启动失败,先检查日志并修复,再重复上述启动命令。保留 stack.env 与数据卷,不要通过重新初始化密钥来修复。
步骤四:验证、登录与首次配置
在服务器检查后端就绪接口和前端页面。就绪响应的 data.status 应为 ok;登录页应返回 HTML。自定义端口时同步修改命令中的 18080。
curl -fsS http://127.0.0.1:18080/health/ready
curl -fsS -o /dev/null http://127.0.0.1:18080/loginssh -N -L 18080:127.0.0.1:18080 deploy-user@server.example.com替换 SSH 用户与服务器地址并保持终端运行,然后在本机浏览器打开 http://127.0.0.1:18080/login。默认端口不对公网监听,仅开放防火墙无法直接用公网 IP 访问。
- 在服务器上私下查看 deploy/stack.env 中的 BOS_ADMIN_EMAIL 和 BOS_ADMIN_PASSWORD。up 完成后提示凭证文件位置;单独执行 init 会显示初始凭证。首次登录需绑定 MFA 验证器。
- 登录后按下文“保存实际 API 地址”设置最终入口,再配置上游账号或 API Key、渠道与模型,创建组织并分配渠道/模型,最后创建该组织的网关 Key,验证一次真实授权调用及其用量记录。
- 就绪检查验证数据库连接,Redis 仍需结合容器状态与实际功能确认。部署不包含模型额度或上游权限,还需验证管理员登录和实际模型请求。
首次配置 Nginx 静态访问
应用启动并成功发布前端后,配置同一宿主机上的 Nginx。下列片段适用于默认静态目录和 18080 端口;如有现存站点,先备份并合并配置,保留证书、域名及其他站点设置。部署脚本不会安装、修改或重载 Nginx。
sudo mkdir -p /etc/nginx/snippets
sudo cp deploy/nginx/bosapi-proxy.conf /etc/nginx/snippets/
sudo cp deploy/nginx/bosapi-static.conf /etc/nginx/snippets/将 deploy/nginx/bosapi-connection.conf 中的 map 配置放入 Nginx http 上下文一次;已有同名 map 时复用。http 上下文还需加载 mime.types。自定义端口时修改 bosapi-proxy.conf。
server {
listen 80;
server_name bosapi.example.com;
client_max_body_size 128m;
include /etc/nginx/snippets/bosapi-static.conf;
}替换域名并按服务器现有方式启用站点。公网正式使用需配置 HTTPS;已有 HTTPS 站点可保留 TLS 设置,将原兜底 location / 替换为该 include。此示例不会申请证书。
sudo nginx -t && sudo systemctl reload nginx
curl -fsS https://bosapi.example.com/health/ready
curl -fsS -o /dev/null https://bosapi.example.com/login使用已配置的实际域名和协议;仅配置上述 HTTP 示例时使用 http://。另需从浏览器验证前端页面、静态资源、登录和流式模型调用。
- Nginx 直接读取 /var/www/bosapi/current,API 转发到 127.0.0.1:18080。应用端口保持回环监听,公网开放所需的 80 / 443。
- 切到 Nginx 静态模式后,首次部署和更新均使用 ./deploy/stack.sh up --source。不要用 install.sh --local 更新此模式:该安装入口每次会将 BOS_WEB_DELIVERY 改为 go。
- 若仅静态发布失败,后端可能已经更新。修复目录或发布错误后执行 ./deploy/stack.sh publish-web 重试;这不会回滚后端或数据库。
可选替代:通过 Caddy 启用 HTTPS
不使用 Nginx 静态访问时,可改由 Go 提供前端、Caddy 提供 HTTPS。先将域名的 A / AAAA 记录指向服务器,确保 80 / 443 未被其他服务占用,并在防火墙和云安全组放行。以下命令在同一套已初始化的实例上增加 HTTPS。
BOS_WEB_DELIVERY=go
BOS_INSTALL_DOMAIN=api.example.com替换示例域名,保留其余配置。BOS_INSTALL_DOMAIN 为不带协议、路径或端口的域名。客户端使用的 API 地址还需在后台单独保存,见下一节。
touch deploy/https.enabled
./deploy/stack.sh up --source
./deploy/stack.sh status标记使 stack.sh 合并 Caddy 和已启用的监控、更新器配置。此命令沿用本指南的源码部署模式;已有固定镜像且只增加 HTTPS 时用 ./deploy/stack.sh start。Caddy 自动申请和续期证书,up --wait 不验证公网证书,继续检查 HTTPS。
curl -fsS https://api.example.com/health/ready
curl -fsS -o /dev/null https://api.example.com/login将域名替换为实际值;证书签发可能需要等待。完成后从外部网络访问登录页。直接 Compose 命令仍须显式添加 HTTPS 和其他已启用的 overlay。
- 已有 1Panel、Nginx 或其他 HTTPS 入口时,可复用其反向代理,不启动 Caddy。代理在宿主机运行时可转发到 127.0.0.1:18080;容器内的 127.0.0.1 指向代理容器自身,需另行规划连通方式。
- 保留流式响应转发,并将代理读取超时设为至少与 BOS_GATEWAY_TIMEOUT_SECONDS 相同(默认 300 秒)。
步骤五:保存实际 API 地址
在选定的 Nginx、Caddy 或其他入口可用后,以超级管理员进入“设置 > API 地址”,保存客户端实际能访问的地址,例如 https://api.example.com。此设置保存在当前数据库;已有实例也应核对是否残留旧域名或测试环境地址。
curl -fsS http://127.0.0.1:18080/api/v1/platform/config
curl -fsS https://api.example.com/api/v1/platform/config替换实际域名、协议和后端端口。两个响应的 data.gateway_endpoint 应与保存的地址一致;新数据库未配置时为空。
- 前端通过 /api/v1/platform/config 读取此地址,文档和客户端示例据此生成 /v1 基址;未配置时显示 YOUR_API_ADDRESS。VITE_GATEWAY_URL、BOS_PRIMARY_DOMAIN 和 Caddy 的 BOS_INSTALL_DOMAIN 都不能替代这项后台设置。
- SSH 隧道中的 127.0.0.1:18080 仅适合使用同一台电脑、同一条隧道的本机客户端。为远程用户提供服务时保存其可达的公网或内网入口;容器内部的 app:8081 不能作为普通外部客户端地址。
常用配置与构建网络
| 字段 | 用途 |
|---|---|
| BOSAPI_PORT | 应用宿主机端口,默认 18080,绑定范围由 BOSAPI_BIND_IP 控制;不改变 MySQL 固定的 13306 映射。 |
| BOSAPI_BIND_IP | 默认 127.0.0.1。无需 Nginx 的 --local --public 安装会保存 0.0.0.0,并由后续 Compose 和更新命令复用;公网访问还需允许安全组与主机防火墙的对应 TCP 端口。 |
| BOS_WEB_DELIVERY | 默认 nginx,由 Nginx 提供静态文件;go 由应用提供前端并跳过静态发布。up --source 保留已有模式。 |
| BOS_WEB_ROOT | 默认 /var/www/bosapi,仅静态发布使用。自定义时同步修改 Nginx 配置中的两个静态根路径。 |
| BOS_GATEWAY_TIMEOUT_SECONDS | 上游请求超时,默认 300,必须是正整数秒;代理超时应同步调整。 |
| BOS_MAX_REQUEST_BODY_MB | 请求体大小配置,Compose 默认 128;公网代理的请求体限制也需匹配。 |
| BOS_GEMINI_OAUTH_CLIENT_ID / BOS_GEMINI_OAUTH_CLIENT_SECRET | 可选 Gemini CLI / Code Assist 客户端覆盖。两项均为空时使用内置默认值,覆盖时必须成对设置。 |
| BOS_ANTIGRAVITY_OAUTH_CLIENT_ID / BOS_ANTIGRAVITY_OAUTH_CLIENT_SECRET | 可选 Antigravity 客户端覆盖,与 Gemini 独立。两项均为空时使用内置默认值,单项设置会报错。 |
| BOS_MYSQL_IMAGE / BOS_REDIS_IMAGE | 数据服务镜像来源;保持与当前项目兼容的版本。 |
| BOS_BASE_IMAGE_REGISTRY / BOS_GOPROXY | 应用构建使用的基础镜像前缀与 Go 模块源;变更后需重新构建。 |
BOS_MYSQL_IMAGE=mysql:8.4
BOS_REDIS_IMAGE=redis:7.4-alpine
BOS_BASE_IMAGE_REGISTRY=docker.io/library
BOS_GOPROXY=https://proxy.golang.org仅在这些源从服务器可达时使用。BOS_BASE_IMAGE_REGISTRY 不含 https://。保留配置文件中的其他字段,不必为了切换网络重新生成密码。
- Compose 文件默认包含镜像加速源和 goproxy.cn。网络受限时,在 stack.env 中选择实际可达的镜像与模块源;切换地址不保证下载更快。
- Shell 中同名的环境变量可覆盖 --env-file 的值;配置结果不符时检查当前终端环境。不要公开输出展开后的 docker compose config,它包含服务密码。
官方订阅 OAuth 配置生效
Gemini CLI 与 Antigravity 默认客户端已内置,常规部署无需填写上述覆盖项。使用兼容自定义客户端时,在原私有 deploy/stack.env 中成对填写,保留原密码与加密密钥。先部署新版后端和 Compose 定义;仅环境配置变更时执行下列命令,使用现有镜像重建受影响容器。普通容器 restart 不会注入新变量;部署栈不读取 backend/.env.example。
./deploy/stack.sh start日常运维与配置生效
日常操作使用 stack.sh,可自动加载已启用的 HTTPS、监控和更新器编排,并在 Nginx 模式自动发布前端。需要查看各组件日志时,可使用显式指定配置的 Compose 命令。
docker compose --env-file deploy/stack.env \
-f deploy/docker-compose.yml ps
docker compose --env-file deploy/stack.env \
-f deploy/docker-compose.yml logs -f app mysql redis按 Ctrl+C 停止跟随日志,服务继续运行。
./deploy/stack.sh down./deploy/stack.sh start仅执行 restart 不会加载新环境变量。start 不构建新代码;变更源码、Dockerfile 或构建参数时使用 ./deploy/stack.sh up --source。
./deploy/stack.sh status
./deploy/stack.sh logs脚本使用同一 Compose 文件和私有配置;存在 deploy/https.enabled 时自动加载 Caddy 编排。直接 Compose 命令仍需手动添加已启用的 overlay。
持久化与备份恢复
| 对象 | 默认位置 |
|---|---|
| 私有配置 | 部署目录内 deploy/stack.env,含恢复数据所需的原始加密密钥;固定镜像部署另保留 deploy/image.env。 |
| MySQL 数据与迁移历史 | bosapi-stack_mysql_data → /var/lib/mysql。 |
| Redis 数据 | bosapi-stack_redis_data → /data。 |
| 网关数据 | bosapi-stack_gateway_data → /app/data。 |
| HTTPS(可选) | deploy/https.enabled、Caddyfile 与 bosapi-stack_caddy_data / bosapi-stack_caddy_config。 |
- 上表是默认命名卷;如使用自定义挂载,按实际卷或目录备份。停止服务的 down 保留卷;down -v、删除卷或清空挂载目录会删除数据。
- 在维护窗口暂停写入,使用一致的数据库备份,或停栈后备份各数据卷。不要直接复制运行中的 MySQL 数据目录。
- 将原始私有配置、数据、部署提交号、可恢复的应用镜像及代理/证书配置一起备份至服务器之外,并验证恢复。只记下镜像 ID 无法保护镜像不被清理。
- 迁移到新服务器时,先准备同版本代码/镜像,再恢复原配置、原密钥和全部数据到正确挂载位置,最后启动并验证。不要初始化新密钥后连接旧数据库。
更新版本与回滚边界
源码就绪后,更新与首次部署都执行 ./deploy/stack.sh up --source。已有配置会复用,无需再次 init、创建静态目录或重装 Nginx;脚本不自动拉取源码。更新前先确认工作区改动、目标版本、数据库迁移兼容性,以及可恢复的成套备份和旧镜像。
git status --short
git rev-parse HEAD
git fetch --tags origin
git show --no-patch --oneline APPROVED_TAG_OR_COMMIT
git switch --detach APPROVED_TAG_OR_COMMIT先核对 git show 输出和本地改动,再切换版本。不要使用强制 checkout、reset 或覆盖配置来丢弃本地变更。
./deploy/stack.sh up --source
./deploy/stack.sh status
curl -fsS http://127.0.0.1:18080/health/ready保留原始密钥、前端模式、挂载与启用标记。Nginx 模式自动发布前端;更新后再次验证实际域名的 HTTPS、静态资源、管理员登录、模型调用和用量。构建切换可能有短暂中断。
- 数据库迁移嵌入应用镜像,更新 SQL 后需重建。不要编辑已执行的迁移或删除迁移历史来尝试回滚。
- 源码/镜像模式在后端就绪后、前端发布前保存。仅前端发布失败时,运行中的后端及模式记录可能已经更新;检查 status 和 current,修复后用 publish-web 重试。不要与后台镜像更新任务同时执行部署。
- 切回旧镜像不等于撤销数据库变更。先核对旧应用与现有数据库兼容性;不兼容时恢复协调备份。
常见问题与相关文档
| 现象 | 排查方向 |
|---|---|
| 缺少环境变量或未生成 stack.env | up --source 会在 Docker 和静态目录检查通过后按需初始化;先修复前置检查错误。已有数据时恢复原配置,手动 Compose 命令需指定 --env-file 和 -f。 |
| 脚本要求静态目录或 Python | nginx 模式需 Python 3.9+。up 自动创建缺失目录,父目录不可写时需 sudo;已有目录不会自动改权限,start / publish-web 只校验已有目录。无需静态发布时通过可选 init 设置 BOS_WEB_DELIVERY=go,并检查 Shell 覆盖变量。 |
| 上传源码后仍运行旧镜像 | 检查 ./deploy/stack.sh status 和 deploy/image.env。固定镜像时,普通 up 不拉取也不构建;源码更新使用 up --source,镜像更新使用 up --image 加目标引用。 |
| 客户端示例缺少地址或仍显示旧域名 | 在“设置 > API 地址”保存实际入口,再检查 /api/v1/platform/config 的 gateway_endpoint;修改 BOS_PRIMARY_DOMAIN 不会更新此设置。 |
| 镜像拉取或源码编译失败 | 检查服务器网络、镜像/依赖来源、构建内存和磁盘;查看对应构建错误后重试,不删除已有密钥与卷。 |
| 端口冲突或容器不健康 | 检查 18080、13306 及 HTTPS 的 80 / 443;用 ps 和各服务 logs 定位。修改 BOSAPI_PORT 不会改变 MySQL 端口。 |
| 数据库迁移或解密失败 | 核对原始 stack.env、加密密钥、数据挂载与部署版本。保留错误现场,按迁移恢复说明处理,不重复生成配置。 |
| OAuth 回调不可达 | 默认 Compose 将回调监听在容器内 127.0.0.1:1455,未映射到宿主机。Nginx / Caddy 的普通 API 代理与应用健康检查不能验证该流程;按应用仓库的当前限制说明核对。 |
按部署版本核对具体能力与操作。 查看文档适用范围