feat(mixapi): 添加 MIXAPI 部署配置

- 全容器化 stack.yml 与复用 prod-dbs 的 stack.host.yml 双方案 - Dockerfile 从 GitHub Release 下载官方二进制构建（官方无 Docker Hub 镜像） - env.cfg.example 模板与 readme 部署/初始化说明
2026-09-03 21:24:59 +08:00
parent e550b5b2f1
commit 4afb627314
5 changed files with 370 additions and 0 deletions
@@ -0,0 +1,111 @@
+# mixapi
+
+MIXAPI（https://github.com/aiprodcoder/MIXAPI）大模型 API 网关部署。
+MIXAPI 基于 New-API/One-API 二次开发，配置语义与 `../newapi` 同源
+（`SQL_DSN` / `REDIS_CONN_STRING` / `SESSION_SECRET` / `--log-dir` 等一致），
+本目录按 `../newapi` 的结构提供两套部署方案。
+
+## 镜像说明（重要）
+
+MIXAPI 官方**没有发布 Docker Hub 镜像**：仓库 CI 与 README 的分发方式是
+GitHub Release 二进制（或自行 `docker build`）。本目录 `Dockerfile` 即采用
+官方方式——构建时从 GitHub Release 下载与 `IMAGE_TAG_VER` 同名的二进制：
+
+```bash
+docker build --build-arg MIXAPI_VER=v2.5.1cl -t mixapi:v2.5.1cl ./mixapi
+```
+
+- 版本号：`env.cfg` 中 `IMAGE_TAG_VER`（默认 `v2.5.1cl`），需与
+  https://github.com/aiprodcoder/MIXAPI/releases 的 tag 同名；
+- 架构：构建机 x86_64 → amd64，aarch64 → arm64，跨架构构建可用
+  `--build-arg MIXAPI_ARCH=amd64` 显式指定；
+- 若已把镜像推送到私有仓库（如 `hub.tp229.com:3500/mixapi`），把 `env.cfg`
+  的 `IMAGE_TAG` 改为仓库地址，即可跳过本地构建，走常规 `pull`。
+
+## 部署方式 A：全容器化独立栈（stack.yml）
+
+自带 PostgreSQL + Redis，与宿主机已有服务互不冲突：
+
+```bash
+# 1. 数据目录 + 环境变量
+mkdir -pv /data/volumes/mixapi/{data,logs,redis,pgsql_data}
+cp mixapi/env.cfg.example mixapi/env.cfg && vim mixapi/env.cfg   # 填密码
+
+# 2. 构建镜像（首次或升级版本时）
+docker build --build-arg MIXAPI_VER=v2.5.1cl -t mixapi:v2.5.1cl ./mixapi
+
+# 3. 启动 / 状态 / 日志
+docker compose -p mixapi --env-file ./mixapi/env.cfg -f ./mixapi/stack.yml up -d
+docker compose -p mixapi -f ./mixapi/stack.yml ps
+docker compose -p mixapi -f ./mixapi/stack.yml logs -f mixapi
+```
+
+## 部署方式 B：单容器复用 prod-dbs PG + Dev-Redis（stack.host.yml）
+
+场景与 `../newapi/stack.host.yml` 一致：本机已有 `prod-dbs` 项目的
+PostgreSQL 和 `dbSer/redis` 的 Dev-Redis（172.22.10.205，固定 IP，无密码）。
+
+前置条件：
+
+1. `prod-dbs` 已启动，`docker network ls` 能看到 `prod-dbs_default`；
+2. 在 prod-postgres 上为 mixapi 建库建号（与 new_api 库隔离）：
+
+```sql
+CREATE USER mixapi WITH PASSWORD '<strong-password>';
+CREATE DATABASE mixapi OWNER mixapi;
+```
+
+之后：
+
+```bash
+mkdir -pv /data/volumes/mixapi/{data,logs}
+cp mixapi/env.cfg.example mixapi/env.cfg && vim mixapi/env.cfg   # 填 prod-postgres 密码
+docker build --build-arg MIXAPI_VER=v2.5.1cl -t mixapi:v2.5.1cl ./mixapi
+docker compose -p mixapi-host --env-file ./mixapi/env.cfg -f ./mixapi/stack.host.yml up -d
+```
+
+> 若 prod-postgres 已有可复用的专用账号，直接改 `env.cfg` 的
+> `DB_USER` / `DB_NAME` / `DB_PASSWORD` 即可，无需执行上面 SQL。
+
+## 首次初始化
+
+1. 浏览器访问 `http://<host>:<PORT>`（默认 3000）；
+2. 走 `/setup` 初始化页：创建的第一个账号即 root 管理员
+   （勾选「自用模式」可关闭注册/充值等对外功能）；
+3. 登录后先在「设置」里配置渠道（上游 API Key）并开启缓存
+   （栈内已内置 Redis，无需额外配置）。
+
+健康检查：`curl http://127.0.0.1:${PORT}/api/status`
+
+## 端口与同机部署冲突
+
+- MIXAPI 与 newapi 默认端口同为 **3000**，同机部署两者时必须把其中一个
+  的 `PORT` 改掉（`env.cfg`）。
+- 全容器栈 A 的容器 PG/Redis 不映射宿主机端口，无冲突。
+
+## 环境变量要点
+
+| 变量 | 说明 |
+|------|------|
+| `SQL_DSN` | `postgresql://user:pass@host:port/db`；**不设置**则回落使用 `/data` 下的 SQLite（文件名随版本，v2.5.1cl 为 `mix-api.db`） |
+| `REDIS_CONN_STRING` | `redis://:密码@host:6379`；Dev-Redis 无密码时不带 `:密码@` |
+| `SESSION_SECRET` | 会话密钥。设为字面量 `random_string` 会**启动失败**；留空则重启随机（登录态失效）；多节点必须同值 |
+| `CRYPTO_SECRET` | 渠道密钥加密密钥，默认取 `SESSION_SECRET`；**存量数据加密后不可变更** |
+| `NODE_TYPE` | 多节点：主节点默认 `master`，从节点设 `slave` |
+| `STREAMING_TIMEOUT` | 流式无响应超时（秒），默认 120，出现空补全时调大 |
+
+## 升级与备份
+
+- 升级：改 `env.cfg` 的 `IMAGE_TAG_VER` → 重新 `docker build` →
+  `docker compose ... up -d`（数据卷保留，无需迁移）；
+- 备份：全栈 A 备份 `/data/volumes/mixapi/pgsql_data`；若走 SQLite 回退
+  则备份 `/data/volumes/mixapi/data` 下的数据库文件；`SESSION_SECRET` /
+  `CRYPTO_SECRET` 变更会导致会话与已加密渠道失效，升级时保持原值。
+
+## 停止与清理
+
+```bash
+docker compose -p mixapi     -f ./mixapi/stack.yml     down        # 全栈 A
+docker compose -p mixapi-host -f ./mixapi/stack.host.yml down       # 方案 B
+# 数据目录不随 down 删除，需要彻底清理时手动 rm -rf /data/volumes/mixapi
+```