metapi/docs/operations.md

🔧 运维手册

返回文档中心

---

数据备份

方式一：目录备份（SQLite / Desktop，推荐）

如果当前运行的是 SQLite，最简单的备份方式是直接备份数据目录：

• Docker / 本地开发：仓库内的 data/
• Desktop：应用用户数据目录下的 data/ 子目录

# 手动备份
cp -r data/ data-backup-$(date +%Y%m%d)/

# 自动备份（crontab）
0 2 * * * cp -r /path/to/metapi/data/ /path/to/backups/metapi-$(date +\%Y\%m\%d)/

建议：

• 每日自动备份一次
• 保留最近 7~30 天
• Desktop 备份前先退出应用
• 如果当前运行库已切到 MySQL / Postgres，不能只备份 data/
• 备份文件不要提交到 Git

方式二：数据库原生备份（MySQL / PostgreSQL）

如果当前运行库已经切到 MySQL / Postgres，请使用数据库自己的备份工具或云快照，例如 mysqldump、pg_dump、RDS 快照等。

建议：

• 升级、迁移、执行「重新初始化系统」前先做一次库级备份
• 备份对象是当前 metapi 正在使用的运行库，而不只是本地 data/
• 恢复后重启 Metapi 一次，确认它重新连接到了正确的运行库

方式三：应用内导出

在管理后台 → 「导入/导出」页面：

• 全量导出：站点、账号、Token、路由、设置
• 仅账号：站点和账号信息
• 仅偏好：设置和通知配置

导出为 JSON 文件，可用于跨实例迁移。

数据恢复

目录恢复（SQLite / Desktop）

服务端 SQLite 可按下面流程恢复；Desktop 则先退出应用，再替换应用用户数据目录下的 data/ 后重新启动。

# 1. 停止容器
docker compose down

# 2. 替换数据目录
rm -rf data/
cp -r data-backup-20260228/ data/

# 3. 重新启动
docker compose up -d

应用内导入

在管理后台 → 「导入/导出」页面上传之前导出的 JSON 文件。系统会自动校验数据完整性。

数据库恢复（MySQL / PostgreSQL）

如果当前运行库是 MySQL / Postgres，请先用数据库自己的恢复流程把备份恢复到目标库，再重启 Metapi。若实例保存过运行库配置，重启后仍会优先连接该外部库，而不是自动回退到本地 SQLite。

日志排查

Docker 环境

# 查看实时日志
docker compose logs -f

# 查看最近 100 行
docker compose logs --tail 100

# 只看错误
docker compose logs -f 2>&1 | grep -i error

本地开发

npm run dev
# 日志直接输出到终端

Desktop

• 优先使用托盘菜单的 Open Logs Folder
• Desktop 内置后端的数据目录和日志目录都位于应用用户数据目录下

重点关注的日志

关键词	含义	处理方式
auth failed	上游站点鉴权失败	检查账号凭证是否过期
no available channel	路由无可用通道	检查 Token 是否同步、通道是否被冷却
notify failed	通知发送失败	检查通知渠道配置
checkin failed	签到失败	检查账号状态和站点连通性
balance refresh failed	余额刷新失败	检查账号凭证

健康检查

手动检查

# 检查服务是否响应
curl -sS http://localhost:4000/v1/models \
  -H "Authorization: Bearer <PROXY_TOKEN>" | head -5

# 检查特定模型可用性
curl -sS http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer <PROXY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

以上示例默认服务端部署监听 localhost:4000。Desktop 内置后端运行在 127.0.0.1 的动态端口，优先通过应用界面、托盘日志或健康检查日志排查，不要假定固定端口。

自动化监控建议

• 定时请求 /v1/models，检查返回状态码和模型数量
• 定时抽样请求 /v1/chat/completions，检查端到端可用性
• SQLite / Desktop：监控磁盘空间（SQLite WAL 日志可能增长）
• MySQL / Postgres：监控外部数据库空间、连接数和慢查询
• 监控 Docker 容器状态

常见运维操作

清理代理日志

代理日志会持续增长。如果磁盘空间紧张，可在管理后台 → 代理日志页面清理历史记录。

重置账号状态

如果账号状态异常（unhealthy），可以在账号管理页面：

1. 点击「刷新」重新检测账号健康状态
2. 如凭证过期，系统会尝试自动重登录
3. 手动禁用/启用账号

强制刷新模型

在管理后台手动触发：

• 余额刷新：立即更新所有账号余额
• 模型刷新：重新发现所有上游模型
• 签到：立即执行一次签到

系统代理

在管理后台「设置 → 系统代理」中保存全局代理地址后，只有启用了「使用系统代理」的站点才会走这条出站代理。

• 单个站点可在站点页直接开关
• 站点页支持批量开启 / 关闭系统代理
• 修改系统代理地址后，Metapi 会自动失效站点代理缓存，通常无需手工重启

清理缓存并重建路由

• 「设置 → 清除缓存并重建路由」会清空模型发现缓存、自动路由和自动通道，再后台触发一次模型刷新与路由重建
• 「TokenRoutes → 重建路由」适合在调整账号、Token、路由规则后手动重新生成自动路由
• 如果 GET /v1/models、路由列表或选择概率明显滞后，优先执行这一操作

批量操作

管理后台支持以下批量运维动作：

• 站点：批量启用、禁用、删除、开启系统代理、关闭系统代理
• 账号：批量刷新余额、启用、禁用、删除
• Token：批量启用、禁用、删除

批量操作完成后，界面会返回成功/失败数量；删除站点或账号后，路由相关缓存会自动失效。

重新初始化系统

这是高风险操作，位于「设置 → 危险操作」。

• 会清空当前 metapi 正在使用的全部业务数据
• 如果当前运行在外部 MySQL / Postgres，会先清空该外部库中的 metapi 数据，再切回默认 SQLite
• 管理员 Token 会重置为 change-me-admin-token
• 当前登录会话会立即退出，页面刷新后回到首装状态

执行前建议先做一次导出或数据库备份。

发布前检查清单

如果你在本地开发并准备发布：

• npm test 通过
• npm run build 通过
• .env、data/、tmp/ 未提交到 Git
• 敏感凭证已从代码中移除

下一步

• 常见问题 — 常见报错与修复
• 配置说明 — 环境变量详解