deploy.stack/mixapi/readme.md

# 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
```