本地开发部署

在本机运行 Go 后端和 Vite 前端,使用独立的 MySQL、Redis 开发依赖,完成登录、调试与构建验证。

开发环境指南更新于 2026-10-27

前置要求

本指南用于在本机修改和调试 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 / pnpmNode.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 认证方式,不在命令中写入令牌。

在 Node.js 22 环境准备 pnpm
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。也可通过下方链接下载同一份脚本。脚本只生成本地配置,不连接数据库或启动服务。

.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 数据。

.dev/compose.yml
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:
校验并启动 MySQL / Redis
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。

终端 A:加载配置并启动后端
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 配置的默认目标是远程测试服务。

终端 B:启动本机前端并代理本机后端
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/login
登录并保存 API 地址后验证配置
curl -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 redis
停止依赖,保留数据卷
docker compose --env-file .dev/backend.env -f .dev/compose.yml down
使用原配置重新启动依赖
docker 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 修改需重启,静态页面修改需重建。

按部署版本核对具体能力与操作。 查看文档适用范围

BOS API · TYPEX

销售咨询暂不可用

暂时无法初始化销售接待,请稍后重试。你仍可查看文档并免费自托管。

查看文档免费自托管