metapi/docs/configuration.md

⚙️ 配置说明

本文档列出 Metapi 的全部环境变量配置。

返回文档中心

---

必填配置

⚠️ 以下变量必须修改，不要使用默认值。

变量名	说明	默认值
AUTH_TOKEN	管理后台登录令牌	change-me-admin-token
PROXY_TOKEN	代理接口 Bearer Token（下游客户端使用此值作为 API Key）	change-me-proxy-sk-token

基础配置

变量名	说明	默认值
PORT	服务监听端口	4000
DATA_DIR	数据目录（SQLite 数据库存储位置）	./data
TZ	时区	Asia/Shanghai
ACCOUNT_CREDENTIAL_SECRET	账号凭证加密密钥（用于加密存储的上游账号密码）	默认使用 AUTH_TOKEN

定时任务

变量名	说明	默认值	示例
CHECKIN_CRON	自动签到计划	0 8 * * *	每天 8:00
BALANCE_REFRESH_CRON	余额刷新计划	0 * * * *	每小时整点

Cron 表达式格式：分 时 日 月 周（标准五段式）

常用示例：

• 0 8 * * * — 每天 08:00
• 0 */2 * * * — 每 2 小时
• 30 7,12,20 * * * — 每天 07:30、12:30、20:30

智能路由

Metapi 的路由引擎按多因子加权选择最优通道。

成本信号优先级

实测成本（代理日志） → 账号配置成本 → 目录参考价 → 兜底默认值

路由权重参数

变量名	说明	默认值	范围
ROUTING_FALLBACK_UNIT_COST	无成本信号时的默认单价	1	> 0
BASE_WEIGHT_FACTOR	基础权重因子	0.5	0~1
VALUE_SCORE_FACTOR	性价比评分因子	0.5	0~1
COST_WEIGHT	成本权重（越大越偏向低成本通道）	0.4	0~1
BALANCE_WEIGHT	余额权重（越大越偏向余额充足的通道）	0.3	0~1
USAGE_WEIGHT	使用率权重（越大越偏向使用较少的通道）	0.3	0~1

三个权重之和建议为 1.0，但不强制。

路由预设建议

场景	COST_WEIGHT	BALANCE_WEIGHT	USAGE_WEIGHT
成本优先	0.7	0.2	0.1
均衡（默认）	0.4	0.3	0.3
稳定优先	0.2	0.5	0.3
轮转均匀	0.1	0.1	0.8

安全配置

变量名	说明	默认值
ADMIN_IP_ALLOWLIST	管理端 IP 白名单（逗号分隔）	空（不限制）

示例：ADMIN_IP_ALLOWLIST=192.168.1.0/24,10.0.0.1

下游 API Key 策略

除了全局 PROXY_TOKEN，Metapi 支持在管理后台「设置 → 下游 API Key」中创建多个项目级下游 Key。

每个 Key 可独立配置以下约束：

字段	说明	示例
name	Key 名称（仅供标识）	team-backend
expiresAt	过期时间	2026-12-31T23:59:59Z
maxCost	累计费用上限	100（超限后拒绝请求）
maxRequests	累计请求数上限	10000
supportedModels	模型白名单（JSON 数组）	["gpt-4o", "claude-*", "re:deepseek.*"]
allowedRouteIds	可走的路由 ID 白名单	[1, 3, 5]
siteWeightMultipliers	站点权重倍率	{"1": 2.0, "3": 0.5}

模型白名单支持三种匹配模式：

• 精确匹配：gpt-4o
• 通配符：claude-*（glob 风格）
• 正则表达式：re:deepseek.*（re: 前缀）

通知渠道

Webhook

变量名	说明	默认值
WEBHOOK_ENABLED	启用 Webhook 通知	true
WEBHOOK_URL	Webhook 推送地址	空

Bark（iOS 推送）

变量名	说明	默认值
BARK_ENABLED	启用 Bark 推送	true
BARK_URL	Bark 推送地址	空

Server酱

变量名	说明	默认值
SERVERCHAN_ENABLED	启用 Server酱 通知	true
SERVERCHAN_KEY	Server酱 SendKey	空

Telegram Bot

变量名	说明	默认值
TELEGRAM_ENABLED	启用 Telegram 通知	false
TELEGRAM_BOT_TOKEN	Telegram Bot Token（形如 123456:abc）	空
TELEGRAM_CHAT_ID	接收消息的 Chat ID（如 -100xxxx 或 @channel）	空

配置步骤：

1. 创建 Bot：在 Telegram 中搜索 @BotFather，发送 /newbot，按提示设置名称后获取 Bot Token（格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz）
2. 获取 Chat ID：
   • 个人聊天：向你的 Bot 发送任意消息，然后访问 https://api.telegram.org/bot<你的Token>/getUpdates，在返回的 JSON 中找到 chat.id，或者在 Telegram 搜索 @userinfobot 或是 @getmyid_bot。点击 Start，它会立刻回复一串数字（通常是 9 到 10 位）。
   • 群组：将 Bot 邀请进群组，在群内发送消息后同样通过 getUpdates 接口获取群组 Chat ID（通常为负数，如 -1001234567890）
   • 频道：使用频道用户名，如 @your_channel（需先将 Bot 添加为频道管理员）
3. 填入配置：将获取的 Token 和 Chat ID 填入环境变量或在管理后台「通知设置」页面中配置
4. 测试：保存后点击页面上的「测试通知」按钮验证是否收到消息

SMTP 邮件

变量名	说明	默认值
SMTP_ENABLED	启用邮件通知	false
SMTP_HOST	SMTP 服务器地址	空
SMTP_PORT	SMTP 端口	587
SMTP_SECURE	使用 SSL/TLS	false
SMTP_USER	SMTP 用户名	空
SMTP_PASS	SMTP 密码	空
SMTP_FROM	发件人地址	空
SMTP_TO	收件人地址	空

告警控制

变量名	说明	默认值
NOTIFY_COOLDOWN_SEC	相同告警冷却时间（秒），防止同一事件重复通知	300

运行时配置

除环境变量外，以下参数可在管理后台「设置」页面中动态调整，无需重启：

• 路由权重参数
• 通知渠道地址
• SMTP 配置
• 告警冷却时间

运行时配置存储在 SQLite 数据库中，优先级高于环境变量默认值。

下一步

• 部署指南 — Docker Compose 与反向代理
• 客户端接入 — 对接下游应用