一键安装 BOS API
在 Linux 或 macOS 上一键部署 BOS API。已有源码可直接启动,无需 Nginx,并可选择 IP 加端口访问。
选择部署方式
已经上传或克隆完整 BOS API 应用源码时,使用 --local 在原目录构建启动;加上 --public 后可通过服务器 IP 和端口直接访问。前端和 API 都由 Go 应用提供,不需要安装 Nginx 或准备静态目录。
没有源码时,也可保留下方下载源码的一键安装方式。希望手动管理 Compose 配置和构建过程时,使用单独的 Docker Compose 指南。所有方式共用 bosapi-stack 默认容器与数据卷,不要在同一 Docker daemon 创建第二套默认实例。
前置要求
请在实际运行 BOS API 的 Linux 服务器或 Mac 上执行命令,先准备好 Docker。--local 也支持复用当前源码目录中的私有配置;已有数据时保留原始配置与密钥。
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux amd64 / arm64,或 macOS Intel / Apple silicon。Mac 上先启动 Docker Desktop 或其他本机 Docker 运行环境,执行安装时不要加 sudo。 |
| 依赖工具 | 提前安装 Docker、Compose v2(支持 up --wait)、Buildx、Bash、OpenSSL、curl 和 tar。安装入口只检查依赖,不自动安装 Docker;Ubuntu 26.04 可另行执行应用仓库的 deploy/install-docker.sh。 |
| Docker 环境 | 使用本机 Unix socket,确保 docker info 可访问;已有 Docker 缺少 Compose 或 Buildx 时需自行补齐。 |
| 网络与资源 | 构建仍需访问镜像仓库、npm/pnpm、Go 模块源及上游服务;--local 仅跳过 GitHub 源码归档下载。首次安装会编译前后端,请预留内存与磁盘空间。 |
| 端口 | 应用默认 18080,--public 时监听所有 IPv4 接口;未指定时默认仅本机。MySQL 始终为 127.0.0.1:13306,Redis 不发布端口;自动 HTTPS 另需 80 / 443。 |
- 无需在宿主机安装 Go、Node.js、MySQL 或 Redis,构建与数据服务均由 Docker 管理。
- Compose 项目名固定为 bosapi-stack,每个 Docker daemon 仅支持一套默认安装;不要在不同目录同时安装。
已有源码:无需 Nginx 一键启动与更新
将完整 BOS API 应用源码上传到服务器,或克隆到运行主机后,进入包含 install.sh、frontend/、backend/ 和 deploy/ 的应用根目录。这里指 bos-api 应用仓库,不是展示本页面的 boss-api-protal 官网仓库。
首次部署和更新都执行下面同一条命令:首次生成配置并构建启动;更新时先准备新源码,再在原目录重跑,复用原配置与数据。--local 不会自动拉取新代码。
| 自动完成 | 结果 |
|---|---|
| 前端与 API | 写入 BOS_WEB_DELIVERY=go,由应用同时提供网页和 API;无需 Nginx、Python 静态发布或 Caddy。 |
| 公网监听 | --public 保存 BOSAPI_BIND_IP=0.0.0.0;应用宿主机端口由 --port 设置,不改变 MySQL 和 Redis 的隔离方式。 |
| 配置与启动 | 缺少配置时生成随机密码与密钥;复用已有 deploy/stack.env,并通过 stack.sh up --source 构建启动、等待健康与检查登录页。 |
./install.sh --local --public --port 18080命令在源码目录原地构建,不重新下载源码。先确保 docker info、docker compose version 和 docker buildx version 正常;Linux 按 Docker 权限选择是否使用 sudo。
./install.sh --local --port 18080Mac 上不要加 sudo。新安装完成后在本机打开 http://localhost:18080/login;如需局域网访问,也可加 --public,并允许对应网络访问。
- 公网访问前,在该服务器实际关联的云安全组与主机防火墙中允许入方向 TCP 18080;修改端口时使用对应端口。随后访问 http://SERVER_IP:18080/login,将 SERVER_IP 替换为服务器公网 IP。该方式提供 HTTP,不会自动申请 HTTPS 证书。
- --local 只适用于已保存且配套文件完整的安装脚本,不能通过 curl 管道使用,也不能与 --dir 或 --ref 同用;--public 不能与 --domain 同用,已有脚本管理的 HTTPS 实例也不能直接切成 --public。
- 私有配置保存在当前源码目录的 deploy/stack.env。重复执行保留密码、密钥、数据挂载和更新器设置,并重建当前源码;--local 显式选择源码部署,旧镜像固定设置仅在启动成功后由现有 stack.sh 流程移除。
- 已有配置时,重复传入的端口和初始邮箱必须与原配置一致。省略 --public 不会关闭已经保存的公网监听;需要回环访问时,手动将原配置中的 BOSAPI_BIND_IP 改为 127.0.0.1,再使用 stack.sh start 应用。
已有源码:更新后重跑同一命令
以下示例适用于原来使用 --local --public --port 18080 的实例,在服务器原 bos-api 应用目录执行。更新前先备份原 deploy/stack.env、数据库及其他持久化数据,并核对目标版本的数据库迁移。
git status --short
git branch --show-current
git rev-parse HEAD先保留并处理本地修改。下方拉取命令适用于已有跟踪分支、准备更新该分支的仓库;固定标签或提交的部署应先选择目标版本。
git pull --ff-only && ./install.sh --local --public --port 18080--ff-only 无法快进时会停止,&& 确保拉取失败后不会继续部署。仅执行安装命令只会重建当前源码。
./install.sh --local --public --port 18080将完整新源码同步到原目录,保留原 deploy/stack.env、自定义数据目录和启用标记。手动上传的目录可能没有 .git,无需执行 git pull。
./deploy/stack.sh status
curl --noproxy "*" -fsS --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/health/ready再验证浏览器登录、模型调用和用量记录。自定义端口请使用实际端口。
- 重复执行会保留已有密码、密钥和数据挂载,重新构建前后端并启动服务;更新可能有短暂中断。不必先卸载或执行 down,也无需配置 Nginx。
- 仅启动已有镜像、不需要构建时,可使用 ./deploy/stack.sh start。源码更新必须重新构建;仅执行 start 不会部署新代码。
- 仅本机或 HTTPS 部署请沿用原安装参数,不要照抄 --public。不要删除数据卷或重新生成密钥;下载归档安装的更新方式另见备份升级章节。
下载源码:执行一键安装
使用具有 sudo 权限的账号登录服务器,执行以下命令。默认从 main 分支下载源码,安装到 /opt/bosapi。
curl -fsSL https://raw.githubusercontent.com/secure-typex/bos-api/main/install.sh | sudo sh已登录 root 时可省略 sudo。执行前需已具备 curl;脚本执行后才会检查其余依赖。
- 脚本下载完整源码,生成独立随机密码、JWT 签名密钥和数据加密密钥,写入权限为 600 的 deploy/stack.env。
- 通过 Docker Compose 构建并启动应用、MySQL 和 Redis。前端随应用提供,自动配置 BOS_WEB_DELIVERY=go。
- 等待容器健康,并检查 /health/ready 和 /login;完成后输出登录地址、初始管理员账号和随机密码。首次构建可能需要数分钟或更久。
- 若下载提示 404,请先确认仓库和 main/install.sh 可匿名访问,且 main 包含安装脚本及其配套部署文件。
访问并登录
使用 --public 时,放行对应端口后直接访问 http://SERVER_IP:18080/login,无需 Nginx 或 SSH 隧道;使用 --domain 时访问 https://你的域名/login。
未指定 --public 或 --domain 的新安装仅监听本机:在运行主机打开 http://127.0.0.1:18080/login。若应用在远程服务器上,先从自己的电脑建立下方 SSH 隧道。
ssh -N -L 18080:127.0.0.1:18080 deploy-user@server.example.com将 deploy-user 和 server.example.com 替换为实际 SSH 用户和服务器地址,保持终端运行,然后在本机浏览器打开 http://127.0.0.1:18080/login。
- 默认管理员邮箱为 admin@bosapi.local,初始密码由脚本随机生成并在首次安装成功时显示;首次登录需完成 MFA 验证器绑定。
- 如需查找初始账号信息,私下查看实际部署目录的 deploy/stack.env 中的 BOS_ADMIN_EMAIL 和 BOS_ADMIN_PASSWORD;--local 使用原源码目录,默认 root 下载方式使用 /opt/bosapi。在后台改密后,文件中的初始密码不再代表当前密码。
- 公网 HTTP 必须同时满足应用绑定 BOSAPI_BIND_IP=0.0.0.0、端口映射正确、安全组与主机防火墙允许访问。仅修改 BOSAPI_PORT 或仅放行安全组,不会自动把默认回环监听改为公网监听。
可选:首次安装时启用 HTTPS
如需通过域名和 HTTPS 访问,在首次安装时选择 --domain,不能与 --public 同用。已有源码时可执行 ./install.sh --local --domain api.example.com;也可使用下方下载命令。先将域名的 A / AAAA 记录指向本服务器,确保 TCP 80 / 443 空闲,并在服务器防火墙和云安全组中放行。
curl -fsSL https://raw.githubusercontent.com/secure-typex/bos-api/main/install.sh | sudo sh -s -- \
--domain api.example.com \
--admin-email owner@example.com替换示例域名和邮箱。--domain 只接受域名,不包含 https://、路径或端口。
- 脚本增加 Caddy 容器,自动申请和续期证书,并将 HTTP 重定向至 HTTPS。登录入口为 https://api.example.com/login。
- 已有 1Panel、Nginx 或其他服务占用 80 / 443 时,应使用无 --domain 的安装方式,并在现有反向代理中配置 HTTPS,转发至 127.0.0.1:18080;该目标要求代理能访问宿主机回环地址,容器中的 127.0.0.1 指向代理容器自身。
- 脚本会验证本机 HTTPS 证书和就绪接口;安装完成后仍需从外部网络验证域名和防火墙可达性。已安装实例不能通过重跑脚本追加或更换域名。
安装参数
已有源码时在 ./install.sh 后直接传入参数;下载方式通过 sudo sh -s -- 传递参数。--local 必须运行已保存的脚本,不能用于下载管道。Mac 上省略 sudo,所有路径和邮箱均替换为实际值。
| 参数 | 默认值 | 用途 |
|---|---|---|
| --local | 不启用 | 原地构建脚本旁的完整应用源码,复用该目录配置,自动使用 Go 提供前端。不能与 --dir 或 --ref 同用。 |
| --public | 不启用 | 保存应用的 0.0.0.0 IPv4 监听,通过 IP 加端口访问 HTTP;不安装 Nginx,不改变数据库端口。不能与 --domain 同用。 |
| --dir PATH | /opt/bosapi | 指定首次安装目录,必须为不存在的绝对路径。无 sudo 的非 root 用户默认使用 $HOME/.local/share/bosapi。 |
| --ref REF | main | 选择包含安装文件的分支、标签或提交。复现部署时,入口脚本也应从相同标签或提交下载。 |
| --domain DOMAIN | 不启用 | 首次安装时启用 Caddy 公网 HTTPS。 |
| --port PORT | 18080 | 应用宿主机端口(1–65535);默认回环,--public 时为所有 IPv4 接口。已有配置时重复指定必须保持一致。 |
| --admin-email EMAIL | admin@bosapi.local | 设置初始管理员邮箱。 |
| --help | — | 显示参数帮助。 |
curl -fsSL https://raw.githubusercontent.com/secure-typex/bos-api/main/install.sh | sudo sh -s -- \
--dir /srv/bosapi \
--port 19090 \
--admin-email owner@example.com自定义目录或端口后,请同步修改后续命令中的路径、登录地址和 SSH 隧道端口。
部署组件与数据位置
以上卷名为 Compose 逻辑名称,默认实际名称带 bosapi-stack_ 前缀。仅复制源码目录不包含这些 Docker 卷中的数据。
| 组件 / 文件 | 访问与持久化 |
|---|---|
| app | Go 网关与编译后的 React 管理界面,默认 127.0.0.1:18080 → 容器 8081;--public 时宿主机改为 0.0.0.0:18080,无需 Nginx。网关数据保存于 gateway_data 卷。 |
| MySQL 8.4 | 127.0.0.1:13306 → 容器 3306;数据库保存于 mysql_data 卷。 |
| Redis 7.4 | 仅在容器网络访问;AOF 等数据保存于 redis_data 卷。 |
| deploy/stack.env | 私有配置、初始账号信息和加密密钥;请与数据一起备份,勿提交到仓库。 |
| Caddy(可选) | 公网 80 / 443;证书和配置保存于 caddy_data / caddy_config 卷,deploy/https.enabled 自动启用 HTTPS 编排。 |
验证并配置模型接入
进入实际部署目录检查状态:--local 使用原应用源码目录,默认 root 下载方式使用 /opt/bosapi。就绪响应的 data.status 应为 ok;还需从实际使用的浏览器确认登录页和管理界面正常。Linux root 安装按需加 sudo,Mac 上不加。
./deploy/stack.sh status
curl --noproxy "*" -fsS --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/health/readycurl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://SERVER_IP:18080/login替换 SERVER_IP 与自定义端口。命令行返回 200 后,仍需确认浏览器访问;浏览器代理插件可以独立于系统代理生效。
- 首次登录完成 MFA 绑定后,配置自己的上游账号或 API Key、渠道及模型。部署本身不包含模型额度或上游访问权限。
- 创建组织并分配可用渠道与模型,然后为应用创建属于该组织的网关 Key。
- 使用实际可用的模型完成一次授权调用,并核对返回状态、调用记录和用量。健康检查通过不代表上游调用已配置成功。
日常运维
以下命令在实际部署目录执行,并使用安装时的 Docker 用户;Linux root 安装按需加 sudo,Mac 上不要加。--local 的公网绑定保存在 deploy/stack.env,日常启停、源码更新与现有镜像更新器继续使用原流程,无需新增 Nginx 或更换管理方式。logs 会持续跟随日志,按 Ctrl+C 退出查看。
./deploy/stack.sh status
./deploy/stack.sh logs./deploy/stack.sh down./deploy/stack.sh start修改 deploy/stack.env 的运行配置后使用 start 重新创建容器;仅重启容器不会加载新的环境变量。源码部署在保留配置后使用 up --source 重建;现有镜像更新方式保持不变。
常见问题与失败重试
重跑不允许更换既有安装的目录配置参数(ref、域名、端口或初始邮箱)。失败后先检查错误与日志;不要删除数据卷或重新生成密钥来尝试修复。
| 现象 | 处理方法 |
|---|---|
| 下载脚本返回 404 | 确认安装脚本已在指定分支发布且可匿名下载;私有仓库或未发布文件无法使用此公开下载命令。 |
| 缺少 Docker 或依赖工具 | 安装入口不会自动安装依赖。先准备 Docker、Compose v2、Buildx、Bash、OpenSSL、curl 和 tar;Ubuntu 26.04 的 Docker 安装脚本需要单独执行。 |
| 无法连接 Docker | 检查 docker info、docker compose version、docker buildx version;确保本机 daemon 运行且当前用户有权限,不使用远程 Docker context。 |
| 构建很慢或下载失败 | 检查镜像仓库、npm/pnpm 与 Go 模块网络,以及服务器内存和磁盘。修复后用相同目录重试,保留已有配置和数据。 |
| 公网 IP 加端口连接超时 | 确认用了 --public,stack.env 为 BOSAPI_BIND_IP=0.0.0.0,容器发布 0.0.0.0:18080,并在实际关联的安全组中允许入方向 TCP 18080,授权来源覆盖访问者 IP;再检查主机防火墙。默认回环部署仍需 SSH 隧道或首次安装的 --domain。 |
| 命令行正常,浏览器显示 502 | 先对比服务器本机、外部 curl --noproxy "*" 与浏览器请求,不能仅凭容器健康或一次 200 判定浏览器已恢复。检查浏览器自身代理插件、PAC 规则及系统代理;关闭系统代理不一定关闭插件代理,无痕窗口也可能允许插件。 |
| 不识别 --local 或 --public | 确认完整源码和 install.sh 来自支持这两个参数的同一版本,不要只替换脚本或使用旧版 Compose 文件。 |
| 目录已存在或发现旧卷 | 下载方式不接管非脚本创建的目录;已有完整应用源码时使用 --local,复用其私有配置。旧数据存在而 stack.env 丢失时,仍应恢复原配置和加密密钥。 |
./install.sh --local --public --port 18080保持原来的参数与配置,不重置密码或数据;脚本重建当前目录源码,不获取 Git 新版本。私有或 HTTPS 模式请重复原安装参数。
sudo sh /opt/bosapi/install.sh --dir /opt/bosapi若失败发生在源码目录创建之前,重新执行原下载命令。下载方式重跑不升级源码;两种方式均不重置密码,也不重新显示既有初始密码。
备份、升级与相关文档
- 备份原始 deploy/stack.env、MySQL 数据和迁移历史、Redis 与网关数据;启用 HTTPS 时还需备份 https.enabled 和 Caddy 证书/配置卷。将备份保存在服务器之外并验证恢复。
- 需要跨组件一致性时,在维护窗口暂停写入或停栈后备份;不要直接复制运行中的 MySQL 数据目录。缺失原加密密钥将无法解密已有数据。
- 下载方式使用不带 .git 的源码归档,不能直接 git pull,重跑也不升级归档。--local 不获取 Git 更新,只构建已经放入当前目录的源码。升级前验证备份,准备审核后的目标源码,保留原私有配置与启用标记,再按原有升级指南构建验证。
- --local --public 保存的 BOS_WEB_DELIVERY=go 与 BOSAPI_BIND_IP=0.0.0.0 会被后续 stack.sh up --source、start、up --image 和现有镜像更新器复用。更新代码时保留原 stack.env,不必额外安装 Nginx。
- 应用回滚不会撤销数据库迁移。复用旧镜像前需核对数据库兼容性,或恢复成套备份。
按部署版本核对具体能力与操作。 查看文档适用范围