本地开发部署
在本机运行 Go 后端和 Vite 前端,使用独立的 MySQL、Redis 开发依赖,完成登录、调试与构建验证。
前置要求
本指南用于在本机修改和调试 BOS API。Go 后端与 Vite 前端运行在宿主机,Docker Compose 仅提供开发用 MySQL 和 Redis。命令使用 Bash,适用于 macOS、Linux,以及具备对应工具的 Windows WSL2 环境。
| 项目 | 要求 |
|---|---|
| Go | 按当前 backend/README.md 使用 Go 1.26.6 或更新的兼容版本;go.mod 声明 Go 1.26。 |
| Node.js / pnpm | Node.js 22,pnpm 9.15.9(与当前 Dockerfile 的前端构建工具一致)。 |
| Docker | 可用的本机 Docker daemon 与支持 up --wait 的 Compose。已有独立 MySQL 8.4 / Redis 7.4 时,可改用自己的开发实例。 |
| 其他工具 | Git、Bash、OpenSSL、curl;网络可访问源码、镜像仓库、npm/pnpm 与 Go 模块源。 |
go version
node --version
pnpm --version
docker info
docker compose version
openssl version- 使用专门的开发数据库和凭证。后端启动会自动执行数据库迁移,请勿把本地开发配置指向生产数据。
- 本地端口为:前端 3000、后端 8081、OAuth 回调 1455、MySQL 13307、Redis 16380;依赖容器仅绑定回环地址。
步骤一:获取源码与安装前端依赖
克隆 BOS API 应用仓库,在应用仓库根目录完成后续操作。boss-api-protal 是官网文档工程,本机启动命令应在 bos-api 中执行。
git clone https://github.com/secure-typex/bos-api.git bos-api
cd bos-api
git rev-parse HEAD已有源码可跳过克隆。需要登录的仓库请使用已有 Git 认证方式,不在命令中写入令牌。
corepack enable
corepack prepare pnpm@9.15.9 --activate已有匹配版本的 pnpm 可跳过。若发行版未提供 Corepack,可按自己的包管理方式安装 pnpm 9.15.9。
pnpm --dir frontend install --frozen-lockfile依赖安装在本机,使用仓库锁文件;失败时先核对 Node/pnpm 版本和下载源。
步骤二:生成并保存本地配置
将下面的脚本保存为应用仓库内 .dev/init-env.sh(先创建 .dev 目录),然后从仓库根目录执行 bash .dev/init-env.sh。也可通过下方链接下载同一份脚本。脚本只生成本地配置,不连接数据库或启动服务。
#!/usr/bin/env bash
# Run from the bos-api application repository root, not the website repository.
set -euo pipefail
umask 077
mkdir -p .dev
if [[ -e .dev/backend.env ]]; then
printf 'Keep the existing .dev/backend.env and encryption key. Configuration was not replaced.\n' >&2
exit 1
fi
mysql_password=$(openssl rand -hex 24)
mysql_root_password=$(openssl rand -hex 24)
redis_password=$(openssl rand -hex 24)
encryption_key=$(openssl rand -base64 32)
jwt_key=$(openssl rand -hex 32)
admin_password=$(openssl rand -hex 24)
cat > .dev/backend.env <<ENV
MYSQL_DATABASE=bosapi_dev
MYSQL_USER=bosapi_dev
MYSQL_PASSWORD=$mysql_password
MYSQL_ROOT_PASSWORD=$mysql_root_password
REDIS_PASSWORD=$redis_password
BOS_LISTEN=127.0.0.1:8081
BOS_CALLBACK_LISTEN=127.0.0.1:1455
BOS_DATA_FILE=../.dev/gateway.enc
BOS_ENCRYPTION_KEY=$encryption_key
BOS_DATABASE_DSN='bosapi_dev:$mysql_password@tcp(127.0.0.1:13307)/bosapi_dev?charset=utf8mb4&parseTime=true&loc=UTC'
BOS_REDIS_URL=redis://:$redis_password@127.0.0.1:16380/0
BOS_JWT_SIGNING_KEY=$jwt_key
BOS_ADMIN_EMAIL=admin@bosapi.local
BOS_ADMIN_PASSWORD=$admin_password
BOS_WEB_DIR=
BOS_MAX_REQUEST_BODY_MB=128
BOS_GATEWAY_TIMEOUT_SECONDS=300
BOS_USAGE_REPORTING_FORCE_DISABLED=true
TZ=Asia/Shanghai
ENV
chmod 600 .dev/backend.env
printf 'Created .dev/backend.env (mode 600). Read initial administrator credentials privately from this file.\n'
生成的 .dev/backend.env 为权限 600 的私有文件,包含独立随机密码和密钥。再次执行会拒绝覆盖,请保留该文件与原加密密钥。
- 本示例生成的 backend.env 同时兼容 Compose dotenv 与 Shell 赋值。仅对这份自己生成、内容可控的文件使用后文的点命令加载;不要把生产 stack.env 当作 Shell 脚本执行。
- BOS_DATA_FILE=../.dev/gateway.enc 以 backend 为运行目录。更改工作目录时应同步调整为正确的路径,保留原数据和密钥。
- 当前应用仓库忽略 .dev/。检查 git status,确保私有配置、运行数据和密码不会进入提交。
步骤三:启动开发数据库与缓存
将以下内容保存为应用仓库中的 .dev/compose.yml。该配置使用独立项目名 bosapi-local-dev、独立命名卷及宿主机端口 13307 / 16380,不使用生产部署的 bosapi-stack 数据。
name: bosapi-local-dev
services:
mysql:
image: mysql:8.4
ports:
- "127.0.0.1:13307:3306"
environment:
MYSQL_DATABASE: ${MYSQL_DATABASE:?Generate .dev/backend.env first}
MYSQL_USER: ${MYSQL_USER:?Generate .dev/backend.env first}
MYSQL_PASSWORD: ${MYSQL_PASSWORD:?Generate .dev/backend.env first}
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?Generate .dev/backend.env first}
TZ: Asia/Shanghai
command:
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_0900_ai_ci
volumes:
- mysql_data:/var/lib/mysql
healthcheck:
test: ["CMD-SHELL", "MYSQL_PWD=\"$${MYSQL_PASSWORD}\" mysql -h 127.0.0.1 -u \"$${MYSQL_USER}\" -D \"$${MYSQL_DATABASE}\" -Nse 'SELECT 1' >/dev/null 2>&1"]
interval: 10s
timeout: 5s
retries: 20
start_period: 60s
redis:
image: redis:7.4-alpine
ports:
- "127.0.0.1:16380:6379"
environment:
REDIS_PASSWORD: ${REDIS_PASSWORD:?Generate .dev/backend.env first}
command: ["redis-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD:?Generate .dev/backend.env first}"]
volumes:
- redis_data:/data
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$${REDIS_PASSWORD}\" redis-cli ping | grep -q PONG"]
interval: 10s
timeout: 3s
retries: 10
volumes:
mysql_data:
redis_data:
docker compose --env-file .dev/backend.env -f .dev/compose.yml config --quiet
docker compose --env-file .dev/backend.env -f .dev/compose.yml up -d --wait
docker compose --env-file .dev/backend.env -f .dev/compose.yml ps首次拉取镜像和初始化 MySQL 可能需要等待。两个服务应为 healthy,再继续启动后端。
- Go 进程运行在宿主机,数据库与 Redis 地址需使用 127.0.0.1 加映射端口,不能使用容器内的 mysql:3306 或 redis:6379。
- 使用已有本地服务时,跳过此 Compose,按实际地址修改 BOS_DATABASE_DSN 和 BOS_REDIS_URL;仍需保留完整的后台数据库与 JWT 配置。
步骤四:启动 Go 后端
终端 A:从应用仓库根目录加载已生成的私有变量,切换到 backend 后运行。后端读取进程环境变量,不会自动加载 backend/.env 或 .dev/backend.env。
set -a
. ./.dev/backend.env
set +a
cd backend
go mod download
go run .保持终端运行。默认监听 http://127.0.0.1:8081,另占用 127.0.0.1:1455 的 OAuth 回调端口;这一步尚未启动浏览器前端。
- 启动时自动执行待完成的 SQL 迁移;新数据库按 BOS_ADMIN_EMAIL / BOS_ADMIN_PASSWORD 创建初始超级管理员。已有管理员不会被环境变量重置密码。
- 首次配置的随机密码只保存在 .dev/backend.env 中,请在本机私下查看。不要把含凭证的完整环境输出或配置截图发到聊天和工单。
- 不配置数据库时可运行部分网关功能,但这不能验证完整的后台登录、组织、Key 与用量流程。本文保留 MySQL 与 JWT 配置。
步骤五:启动 Vite 前端
终端 B:重新进入应用仓库根目录,执行下列命令。务必显式设置 VITE_BACKEND_URL,当前 Vite 配置的默认目标是远程测试服务。
cd frontend
VITE_BACKEND_URL=http://127.0.0.1:8081 \
VITE_API_BASE_URL=/api/v1 \
pnpm run dev --host 127.0.0.1 --port 3000 --strictPort打开 http://127.0.0.1:3000/login。--strictPort 在 3000 被占用时直接报错,避免 Vite 自动换端口后地址与配置不一致。
- Vite 将 /api、/v1、/images 和 /health 代理到本机 8081。前端 API 基址保留 /api/v1,使管理请求通过同源代理访问后端。
- 当前前端从 /api/v1/platform/config 读取后台保存的 API 地址,已不再使用 VITE_GATEWAY_URL 或 BOS_PRIMARY_DOMAIN 作为地址回退。首次登录后需在“设置 > API 地址”保存本机入口,步骤见下文。
- Vite 变量可另存到 frontend/.env.local,但不要覆盖已有本地配置。修改变量或代理配置后重启 Vite;Go 环境变量变更需重启 Go 进程。
- 前端具有热更新;普通 go run 不会自动重启后端,修改 Go 代码后按 Ctrl+C 停止并重新执行 go run .。
步骤六:验证登录与本地调用
curl -fsS http://127.0.0.1:8081/health/ready
curl -fsS http://127.0.0.1:3000/health/ready
curl -fsS -o /dev/null http://127.0.0.1:3000/logincurl -fsS http://127.0.0.1:8081/api/v1/platform/config
curl -fsS http://127.0.0.1:3000/api/v1/platform/config先按下方说明保存 API 地址。两个响应的 data.gateway_endpoint 均应为 http://127.0.0.1:8081;新数据库尚未配置时该字段为空,属于正常状态。
- 前两个就绪响应的 data.status 应为 ok;该检查验证数据库连接,Redis 状态仍需通过依赖容器和实际功能确认。开发模式的登录页来自 3000;Go 未设置 BOS_WEB_DIR 时,直接访问 8081/login 不提供完整前端。
- 使用 .dev/backend.env 中的初始账号登录并完成 MFA 绑定。在浏览器网络面板确认请求由 3000 的 /api/v1 发出,后端日志来自本机进程。
- 以超级管理员进入“设置 > API 地址”,保存 http://127.0.0.1:8081,再执行上方配置验证命令。文档与客户端示例会使用该地址生成 /v1 基址;未配置时显示 YOUR_API_ADDRESS。此设置存入当前数据库,重启后保留;旧开发库已有地址时也应检查是否仍指向远程环境。
- 如需验证模型请求,配置自己有权限的上游账号或 API Key、渠道与模型,创建组织并分配可用模型,再创建组织网关 Key。安装和本地启动不附带模型额度。
- 先验证允许的调用、返回和记录,再按需求验证权限与异常行为;界面能打开或健康检查通过不等于完整业务验证。
可选:构建并由 Go 提供完整页面
需要验证构建产物时,停止终端 A 的 Go 进程,从仓库根目录执行下面命令。BOS_WEB_DIR 必须指向包含 index.html 的绝对目录。
VITE_API_BASE_URL=/api/v1 pnpm --dir frontend run build
set -a
. ./.dev/backend.env
set +a
export BOS_WEB_DIR="$(pwd)/frontend/dist"
cd backend
go run .打开 http://127.0.0.1:8081/login。此时不需要 Vite 代理;修改前端后需重建才能看到最新静态资源。回到双进程开发时重新加载 backend.env,清空 BOS_WEB_DIR。
- 仓库也提供 make build、make run、make dev-backend 与 make dev-frontend。使用这些入口时仍需先安装前端依赖、加载后端环境,并为 Vite 指定本机代理目标。
停止、重启与保留开发数据
先在两个开发终端分别按 Ctrl+C,正常停止 Go 和 Vite。下列命令仅管理独立的本地 MySQL / Redis,不影响 bosapi-stack 部署。
docker compose --env-file .dev/backend.env -f .dev/compose.yml logs -f mysql redisdocker compose --env-file .dev/backend.env -f .dev/compose.yml downdocker compose --env-file .dev/backend.env -f .dev/compose.yml up -d --wait- 保留 .dev/backend.env、.dev/gateway.enc 与 bosapi-local-dev_mysql_data / bosapi-local-dev_redis_data。原始加密密钥需与数据一起备份。
- down 会保留卷。down -v 或删除命名卷会删除开发数据库与缓存;不要将它们作为修复登录或迁移错误的常规步骤。
- 重新打开终端后,应从仓库根目录加载原 backend.env,再进入 backend 运行。不要在每次启动时重新生成 BOS_ENCRYPTION_KEY。
常见问题与相关文档
| 现象 | 处理方法 |
|---|---|
| 加密密钥或 JWT 校验失败 | 确认已用 set -a 加载原私有文件。加密密钥必须解码为 32 字节;数据库模式下 JWT 密钥至少 32 字节。 |
| 前端请求到了远程环境 | 显式设置 VITE_BACKEND_URL=http://127.0.0.1:8081,保留 VITE_API_BASE_URL=/api/v1,并重启 Vite。 |
| 客户端示例显示 YOUR_API_ADDRESS 或远程地址 | 以超级管理员在“设置 > API 地址”保存 http://127.0.0.1:8081,并检查 /api/v1/platform/config 的 gateway_endpoint。VITE_GATEWAY_URL 和 BOS_PRIMARY_DOMAIN 不再提供回退地址。 |
| 依赖连接失败或数据库拒绝访问 | 核对容器 healthy 状态、13307 / 16380 映射、DSN 和密码。已存在的 MySQL 卷不会因修改初始化环境变量而自动改密。 |
| 8081 或 1455 已占用 | 正常停止占用端口的旧进程。修改 BOS_LISTEN 时同步调整前端代理、后台 API 地址和验证地址。OAuth 授权回跳地址当前固定为 http://localhost:1455/auth/callback;需要 OAuth 时应保留 1455,仅修改 BOS_CALLBACK_LISTEN 不会同步更改回跳地址。 |
| 后台登录失败或缺少管理接口 | 确认 BOS_DATABASE_DSN、BOS_JWT_SIGNING_KEY 和初始化账号配置已加载,迁移成功;改 BOS_ADMIN_PASSWORD 不会重置已有账号。 |
| 本地后端登录页 404 | 开发模式访问 3000/login;只有构建前端并设置 BOS_WEB_DIR 后,Go 才提供完整前端页面。 |
| Go、pnpm 安装或构建失败 | 核对当前项目要求的版本、锁文件、网络和磁盘;Go 修改需重启,静态页面修改需重建。 |
按部署版本核对具体能力与操作。 查看文档适用范围