forked from boos/BoosAPI
docs: complete Docker deployment documentation
- Fix all remaining metapi → boosapi references - Full docker-compose.yml example with healthcheck - .env file pattern with variable interpolation - Complete environment variable reference table - Docker Compose production checklist - Redis/MySQL/PostgreSQL extension configs - Resource limits example - Nginx WebSocket support - Admin panel IP restriction pattern - Upgrade/rollback procedures with commands Signed-off-by: Boos4721 <boos4721@icloud.com>
This commit is contained in:
boos
+214
-24
@@ -10,7 +10,7 @@
|
||||
|------|----------|--------------|----------|
|
||||
| 云服务器 / NAS / 家用主机长期运行 | Docker / Docker Compose / Zeabur | 固定服务地址，例如 `http://your-host:4000` 或反向代理域名 | 你挂载的 `DATA_DIR` / 持久化卷 |
|
||||
| 免费云部署（24h 在线） | Render + TiDB + UptimeRobot | Render 分配的 `.onrender.com` 域名或自定义域名 | TiDB Serverless（外部 MySQL 数据库） |
|
||||
| 个人电脑本地使用 | 桌面版安装包 | 桌面窗口；默认本机客户端直连使用 `http://127.0.0.1:4000`，局域网客户端可使用当前机器 IP + `4000`；如有覆盖则按 `METAPI_DESKTOP_SERVER_PORT` 的实际端口访问 | Electron `app.getPath('userData')/data` |
|
||||
| 个人电脑本地使用 | 桌面版安装包 | 桌面窗口；默认本机客户端直连使用 `http://127.0.0.1:4000`，局域网客户端可使用当前机器 IP + `4000`；如有覆盖则按 `BOOSAPI_DESKTOP_SERVER_PORT` 的实际端口访问 | Electron `app.getPath('userData')/data` |
|
||||
| 二次开发 / 调试 | 本地开发 | 前端 `http://localhost:5173`，后端默认 `http://localhost:4000` | 仓库内 `./data` 或自定义 `DATA_DIR` |
|
||||
|
||||
> [!NOTE]
|
||||
@@ -23,17 +23,17 @@
|
||||
|
||||
这套能力只适用于：
|
||||
|
||||
- 你已经在 K3s / Kubernetes 中部署了 Metapi
|
||||
- 而且当前 Metapi 是通过 Helm release 管理的
|
||||
- 你已经在 K3s / Kubernetes 中部署了 BoosAPI
|
||||
- 而且当前 BoosAPI 是通过 Helm release 管理的
|
||||
|
||||
它不适用于：
|
||||
|
||||
- 只有一个裸 Docker Compose 容器
|
||||
- 想直接从管理后台更新外部 Docker 主机上的容器
|
||||
|
||||
但如果你是老用户，**正在计划从 Docker Compose 迁到 K3s / Helm，以获得滚动更新能力**，那么这一节和对应专题页是值得提前看的。它写的不是“怎么原地升级 Compose”，而是“迁移完成后你会如何使用更新中心”。
|
||||
但如果你是老用户，**正在计划从 Docker Compose 迁到 K3s / Helm，以获得滚动更新能力**，那么这一节和对应专题页是值得提前看的。它写的不是"怎么原地升级 Compose"，而是"迁移完成后你会如何使用更新中心"。
|
||||
|
||||
如果你已经通过 Helm 在 K3s / Kubernetes 中部署 Metapi，并希望在管理后台中：
|
||||
如果你已经通过 Helm 在 K3s / Kubernetes 中部署 BoosAPI，并希望在管理后台中：
|
||||
|
||||
- 查看当前运行版本
|
||||
- 检查 GitHub Releases / Docker Hub 的稳定版
|
||||
@@ -55,7 +55,7 @@
|
||||
|
||||
模板会自动完成：
|
||||
|
||||
- 拉取 `1467078763/metapi:latest` 镜像
|
||||
- 拉取 `1467078763/boosapi:latest` 镜像
|
||||
- 配置 HTTP 端口（4000）
|
||||
- 挂载持久化存储（`/app/data`）
|
||||
- 分配域名
|
||||
@@ -75,7 +75,7 @@
|
||||
|
||||
## Render 一键部署（免费 24h 运行）
|
||||
|
||||
<a href="https://render.com/deploy?repo=https://github.com/cita-777/metapi">
|
||||
<a href="https://render.com/deploy?repo=https://github.com/cita-777/boosapi">
|
||||
<img alt="Deploy to Render" src="https://render.com/images/deploy-to-render-button.svg" height="28">
|
||||
</a>
|
||||
|
||||
@@ -83,7 +83,7 @@
|
||||
|
||||
| 组件 | 作用 | 免费额度 |
|
||||
|------|------|----------|
|
||||
| [Render](https://render.com) | 运行 Metapi 容器 | Free Web Service（750 小时/月，闲置 15 分钟自动休眠） |
|
||||
| [Render](https://render.com) | 运行 BoosAPI 容器 | Free Web Service（750 小时/月，闲置 15 分钟自动休眠） |
|
||||
| [TiDB Serverless](https://tidbcloud.com) | MySQL 兼容数据库，替代 SQLite 实现数据持久化 | 5 GiB 存储 + 5000 万 Request Units/月 |
|
||||
| [UptimeRobot](https://uptimerobot.com) | 每 5 分钟 ping 一次，防止 Render 免费实例休眠 | 50 个免费监控 |
|
||||
|
||||
@@ -101,13 +101,13 @@
|
||||
4. 使用面板中显示的参数拼接 `DB_URL`：
|
||||
|
||||
```
|
||||
mysql://<USERNAME>:<PASSWORD>@<HOST>:4000/test?ssl={"rejectUnauthorized":true}
|
||||
mysql://<USERNAME>:***@<HOST>:4000/test?ssl={"rejectUnauthorized":true}
|
||||
```
|
||||
|
||||
> ⚠️ 注意：`<HOST>`、`<USERNAME>`、`<PASSWORD>` 从 Connect 面板中获取，**数据库名必须用 `test` 而非默认的 `sys`**。
|
||||
|
||||
> [!TIP]
|
||||
> 这里只是以TiDB作为示例，你也可以使用其他提供免费额度的云数据库方案（如 Neon、Supabase 等），只需将 `DB_TYPE` 设为对应的 `mysql` 或 `postgres`，并填入正确的连接串即可。什么？你不会其他的？把步骤复制给Gemini问他怎么改。
|
||||
> 这里只是以 TiDB 作为示例，你也可以使用其他提供免费额度的云数据库方案（如 Neon、Supabase 等），只需将 `DB_TYPE` 设为对应的 `mysql` 或 `postgres`，并填入正确的连接串即可。
|
||||
|
||||
### 步骤 2：部署到 Render
|
||||
|
||||
@@ -120,7 +120,7 @@
|
||||
**方式二：手动创建**
|
||||
|
||||
1. 在 [Render Dashboard](https://dashboard.render.com) 点击 **New → Web Service**
|
||||
2. 连接你的 GitHub 仓库（或使用公开仓库地址 `https://github.com/cita-777/metapi`）
|
||||
2. 连接你的 GitHub 仓库（或使用公开仓库地址 `https://github.com/cita-777/boosapi`）
|
||||
3. 配置：
|
||||
- **Environment**: Docker
|
||||
- **Dockerfile Path**: `./docker/Dockerfile`
|
||||
@@ -128,14 +128,14 @@
|
||||
- **Instance Type**: Free
|
||||
4. 添加环境变量（见下表）
|
||||
|
||||
### 环境变量配置
|
||||
### 环境变量配置（Render）
|
||||
|
||||
| 变量 | 说明 | 示例值 |
|
||||
|------|------|--------|
|
||||
| `AUTH_TOKEN` | 管理后台登录令牌（**必填**） | 你的强密码 |
|
||||
| `PROXY_TOKEN` | 代理接口 Bearer Token（**必填**） | 你的代理密钥 |
|
||||
| `DB_TYPE` | 数据库类型（**必填**） | `mysql` |
|
||||
| `DB_URL` | TiDB 连接串（**必填**） | `mysql://user:pass@host:4000/db?ssl=...` |
|
||||
| `DB_URL` | TiDB 连接串（**必填**） | `mysql://user:***@host:4000/db?ssl=...` |
|
||||
| `DB_SSL` | 启用 SSL 连接 | `true` |
|
||||
| `TZ` | 时区 | `Asia/Shanghai` |
|
||||
| `PORT` | 服务端口（默认即可） | `4000` |
|
||||
@@ -163,18 +163,39 @@ Render 免费实例在 15 分钟无流量后会自动休眠。使用 UptimeRobot
|
||||
```bash
|
||||
mkdir boosapi && cd boosapi
|
||||
|
||||
# 创建 docker-compose.yml（参见快速上手）
|
||||
# 设置环境变量
|
||||
export AUTH_TOKEN=your-admin-token
|
||||
export PROXY_TOKEN=your-proxy-sk-token
|
||||
# 创建 docker-compose.yml
|
||||
cat > docker-compose.yml << 'EOF'
|
||||
services:
|
||||
boosapi:
|
||||
image: 1467078763/boosapi:latest
|
||||
container_name: boosapi
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "4000:4000"
|
||||
environment:
|
||||
- AUTH_TOKEN=your-admin-token
|
||||
- PROXY_TOKEN=your-proxy-sk-token
|
||||
- TZ=Asia/Shanghai
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4000/healthz"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
EOF
|
||||
|
||||
# 启动
|
||||
docker compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### 使用 `.env` 文件
|
||||
|
||||
如果不想每次 export，可以创建 `.env` 文件：
|
||||
如果不想把密钥写在 `docker-compose.yml` 里，可以创建 `.env` 文件：
|
||||
|
||||
```bash
|
||||
# .env
|
||||
@@ -184,14 +205,112 @@ TZ=Asia/Shanghai
|
||||
PORT=4000
|
||||
```
|
||||
|
||||
然后在 `docker-compose.yml` 中引用：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
boosapi:
|
||||
image: 1467078763/boosapi:latest
|
||||
container_name: boosapi
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "${PORT:-4000}:${PORT:-4000}"
|
||||
environment:
|
||||
- AUTH_TOKEN=${AUTH_TOKEN}
|
||||
- PROXY_TOKEN=${PROXY_TOKEN}
|
||||
- TZ=${TZ:-Asia/Shanghai}
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
```
|
||||
|
||||
启动时指定 env 文件：
|
||||
|
||||
```bash
|
||||
docker compose --env-file .env up -d
|
||||
```
|
||||
|
||||
> ⚠️ `.env` 文件包含敏感信息，请勿提交到 Git 仓库。
|
||||
> ⚠️ `.env` 文件包含敏感信息，请勿提交到 Git 仓库。确保已添加到 `.gitignore`。
|
||||
|
||||
### 全部环境变量
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `AUTH_TOKEN` | 管理后台登录令牌（**必填**） | `change-me-admin-token` |
|
||||
| `PROXY_TOKEN` | 下游客户端调用 `/v1/*` 的 Bearer Token（**必填**） | — |
|
||||
| `PORT` | HTTP 监听端口 | `4000` |
|
||||
| `HOST` | 监听地址 | `0.0.0.0` |
|
||||
| `DATA_DIR` | 数据目录 | `/app/data` |
|
||||
| `TZ` | 时区 | `UTC` |
|
||||
| `DB_TYPE` | 数据库类型：`sqlite` / `mysql` / `postgres` | `sqlite` |
|
||||
| `DB_URL` | 数据库连接串（外部数据库时必填） | — |
|
||||
| `DB_SSL` | 启用数据库 SSL 连接 | `false` |
|
||||
| `LOG_LEVEL` | 日志级别：`debug` / `info` / `warn` / `error` | `info` |
|
||||
| `REDIS_URL` | Redis 连接串（可选，用于缓存/速率限制） | — |
|
||||
| `BOOSAPI_DESKTOP` | 桌面版标记（请勿手动设置） | — |
|
||||
| `BOOSAPI_LOG_DIR` | 桌面版日志目录（请勿手动设置） | — |
|
||||
|
||||
### Docker Compose 扩展配置
|
||||
|
||||
#### 挂载自定义目录
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /your/custom/data/path:/app/data
|
||||
```
|
||||
|
||||
#### 使用外部数据库（MySQL/PostgreSQL）
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- DB_TYPE=mysql
|
||||
- DB_URL=mysql://user:password@host:3306/boosapi?ssl={"rejectUnauthorized":true}
|
||||
- DB_SSL=true
|
||||
```
|
||||
|
||||
#### 使用 Redis 加速
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- REDIS_URL=redis://:password@redis:6379/0
|
||||
|
||||
# 额外声明 Redis 服务（可选）
|
||||
services:
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ./redis-data:/data
|
||||
```
|
||||
|
||||
#### 资源限制
|
||||
|
||||
```yaml
|
||||
services:
|
||||
boosapi:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 1G
|
||||
reservations:
|
||||
memory: 256M
|
||||
```
|
||||
|
||||
### Docker Compose 生产部署检查清单
|
||||
|
||||
- [ ] `AUTH_TOKEN` 和 `PROXY_TOKEN` 使用强随机密码
|
||||
- [ ] `.env` 文件已加入 `.gitignore`
|
||||
- [ ] 宿主机端口不与现有服务冲突
|
||||
- [ ] 数据目录已挂载且定期备份
|
||||
- [ ] 启用了 `restart: unless-stopped`
|
||||
- [ ] 配置了健康检查
|
||||
- [ ] 日志轮转已配置（Docker 默认 json-file 会撑满磁盘）
|
||||
|
||||
---
|
||||
|
||||
## Docker 命令部署
|
||||
|
||||
适合快速测试或单容器场景：
|
||||
|
||||
```bash
|
||||
docker run -d --name boosapi \
|
||||
-p 4000:4000 \
|
||||
@@ -200,13 +319,35 @@ docker run -d --name boosapi \
|
||||
-e TZ=Asia/Shanghai \
|
||||
-v ./data:/app/data \
|
||||
--restart unless-stopped \
|
||||
1467078763/metapi:latest
|
||||
1467078763/boosapi:latest
|
||||
```
|
||||
|
||||
> **路径说明：**
|
||||
> - `./data:/app/data` — 相对路径，数据存到当前目录下的 `data` 文件夹
|
||||
> - 也可以使用绝对路径：`/your/custom/path:/app/data`
|
||||
|
||||
### Docker Run 常用选项
|
||||
|
||||
| 选项 | 作用 |
|
||||
|------|------|
|
||||
| `-d` | 后台运行 |
|
||||
| `--restart unless-stopped` | 宕机或宿主机重启后自动拉起 |
|
||||
| `--name boosapi` | 固定容器名，方便管理 |
|
||||
| `-p 4000:4000` | 宿主机端口:容器端口 |
|
||||
| `-v ./data:/app/data` | 持久化数据 |
|
||||
| `-e VAR=value` | 设置环境变量 |
|
||||
| `--network host` | 使用宿主机网络（Linux 专用，跳过端口映射） |
|
||||
| `--log-opt max-size=10m --log-opt max-file=3` | 限制日志大小 |
|
||||
|
||||
### 停止与删除
|
||||
|
||||
```bash
|
||||
docker stop boosapi
|
||||
docker rm boosapi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 桌面版部署（Windows / macOS / Linux）
|
||||
|
||||
桌面版面向个人电脑本地使用，基本安装与配置流程见 [快速上手 → 桌面版启动](./getting-started.md#方式二-桌面版启动-windows-macos-linux)。
|
||||
@@ -215,7 +356,7 @@ docker run -d --name boosapi \
|
||||
|
||||
### 桌面版特性
|
||||
|
||||
- 内置本地 Metapi 服务，无需手动准备 Node.js 运行环境
|
||||
- 内置本地 BoosAPI 服务，无需手动准备 Node.js 运行环境
|
||||
- 托盘菜单支持重新打开窗口、重启后端、开机自启
|
||||
- 支持基于 GitHub Releases 的应用内更新检查
|
||||
|
||||
@@ -238,6 +379,8 @@ Linux 安装包选择建议：
|
||||
- Debian / Ubuntu / Linux Mint 优先使用 `.deb`
|
||||
- 其他发行版可使用 `.AppImage`
|
||||
|
||||
---
|
||||
|
||||
## 本地开发运行（源码调试）
|
||||
|
||||
开发、调试或提交 PR 的完整流程见 [快速上手 → 本地开发启动](./getting-started.md#方式三-本地开发启动) 和 [CONTRIBUTING.md](../CONTRIBUTING.md)。
|
||||
@@ -249,7 +392,7 @@ Linux 安装包选择建议：
|
||||
|
||||
## 反向代理
|
||||
|
||||
以下反向代理配置面向 Docker / 服务器模式。桌面版内置后端默认监听 `0.0.0.0:4000`，但通常仍作为单机桌面应用使用；如果要给局域网或公网客户端访问，请自行配置防火墙、反向代理和认证边界。若你显式设置了 `METAPI_DESKTOP_SERVER_PORT`，请把示例里的 `4000` 改成对应端口。
|
||||
以下反向代理配置面向 Docker / 服务器模式。桌面版内置后端默认监听 `0.0.0.0:4000`，但通常仍作为单机桌面应用使用；如果要给局域网或公网客户端访问，请自行配置防火墙、反向代理和认证边界。若你显式设置了 `BOOSAPI_DESKTOP_SERVER_PORT`，请把示例里的 `4000` 改成对应端口。
|
||||
|
||||
### Nginx
|
||||
|
||||
@@ -279,7 +422,11 @@ server {
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# 超时设置（长对话场景）
|
||||
# WebSocket 支持
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# 超时设置（长对话/SSE 场景）
|
||||
proxy_read_timeout 300s;
|
||||
proxy_send_timeout 300s;
|
||||
}
|
||||
@@ -296,6 +443,28 @@ your-domain.com {
|
||||
}
|
||||
```
|
||||
|
||||
### 限制管理后台访问
|
||||
|
||||
如果只想暴露 API 给客户端，限制后台管理界面只能内网访问：
|
||||
|
||||
```nginx
|
||||
# 管理后台：仅内网
|
||||
location /admin/ {
|
||||
allow 10.0.0.0/8;
|
||||
allow 172.16.0.0/12;
|
||||
allow 192.168.0.0/16;
|
||||
deny all;
|
||||
proxy_pass http://127.0.0.1:4000/;
|
||||
}
|
||||
|
||||
# API：对外
|
||||
location /v1/ {
|
||||
proxy_pass http://127.0.0.1:4000;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 升级
|
||||
|
||||
```bash
|
||||
@@ -309,12 +478,33 @@ docker compose up -d
|
||||
docker image prune -f
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> 建议升级前先备份数据目录。完整备份策略见 [运维手册 → 数据备份](./operations.md#数据备份)。
|
||||
|
||||
---
|
||||
|
||||
## 回滚
|
||||
|
||||
如果升级后出现问题，请参考 [运维手册 → 数据备份与恢复](./operations.md#数据备份) 进行回滚。
|
||||
如果升级后出现问题：
|
||||
|
||||
1. 停止当前容器：`docker compose down`
|
||||
2. 指定旧版本标签重新启动：
|
||||
|
||||
```bash
|
||||
# 查看本地已有镜像
|
||||
docker images 1467078763/boosapi
|
||||
|
||||
# 指定旧版本启动
|
||||
docker compose run --rm boosapi --tag <old-version>
|
||||
# 或修改 docker-compose.yml 中的 image 标签后重新 up
|
||||
```
|
||||
|
||||
3. 如数据也受影响，从备份恢复（见 [运维手册 → 数据备份与恢复](./operations.md#数据备份)）
|
||||
|
||||
核心思路：升级前备份数据目录（或数据库），出问题时停止服务、还原数据、指定旧版镜像重启。
|
||||
|
||||
---
|
||||
|
||||
## 数据持久化
|
||||
|
||||
不同运行方式的数据目录不同：
|
||||
|
||||
Reference in New Issue
Block a user