⚙️ 配置说明
本文档列出 Metapi 的环境变量，并单独说明管理后台中的运行时设置。
返回文档中心
配置来源
| 配置类型 |
入口 |
生效方式 |
适用场景 |
| 环境变量 |
.env / 容器环境变量 |
服务启动时读取，作为启动配置或默认值 |
部署、容器编排、首次初始化 |
| 运行时设置 |
管理后台「设置」 |
持久化到当前运行数据库；大部分即时生效，数据库运行配置保存后需重启 |
在线调整、运维排障 |
必填配置
⚠️ 以下变量必须修改，不要使用默认值。
| 变量名 |
说明 |
默认值 |
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 |
SYSTEM_PROXY_URL |
系统代理 URL（留空表示不使用） |
空 |
ACCOUNT_CREDENTIAL_SECRET |
账号凭证加密密钥（用于加密存储的上游账号密码） |
默认使用 AUTH_TOKEN |
数据库配置
| 变量名 |
说明 |
默认值 |
DB_TYPE |
运行数据库类型：sqlite / mysql / postgres |
sqlite |
DB_URL |
数据库连接串；使用 mysql / postgres 时必填 |
空 |
DB_SSL |
连接 MySQL / Postgres 时启用 SSL |
false |
DB_TYPE=sqlite 时，DB_URL 留空即可，服务会使用默认 SQLite 路径。
定时任务
| 变量名 |
说明 |
默认值 |
示例 |
CHECKIN_CRON |
自动签到计划 |
0 8 * * * |
每天 8:00 |
BALANCE_REFRESH_CRON |
余额刷新计划 |
0 * * * * |
每小时整点 |
Cron 表达式格式：分 时 日 月 周（标准五段式）
常用示例：
0 8 * * * — 每天 08:000 */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，但不强制。
路由缓存
| 变量名 |
说明 |
默认值 |
范围 |
TOKEN_ROUTER_CACHE_TTL_MS |
Token 路由缓存 TTL（毫秒） |
1500 |
>= 100 |
路由预设建议
| 场景 |
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 |
适合测试场景，尽量让每个通道都被使用到 |
调参建议：
- 如果某个站点总是被选中导致余额很快耗尽 → 调高
BALANCE_WEIGHT
- 如果你有几个很便宜的站点想优先用 → 调高
COST_WEIGHT
- 如果你想让请求均匀分散到所有站点 → 调高
USAGE_WEIGHT
- 如果你需要对特定项目偏好某个站点 → 使用下游 API Key 的
siteWeightMultipliers 而非调全局权重
代理日志保留
| 变量名 |
说明 |
默认值 |
范围 |
PROXY_LOG_RETENTION_DAYS |
代理日志保留天数 |
30 |
>= 0 |
PROXY_LOG_RETENTION_PRUNE_INTERVAL_MINUTES |
代理日志清理任务执行间隔（分钟） |
30 |
>= 1 |
安全配置
| 变量名 |
说明 |
默认值 |
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） |
空 |
配置步骤：
- 创建 Bot：在 Telegram 中搜索 @BotFather，发送
/newbot，按提示设置名称后获取 Bot Token（格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz）
- 获取 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 添加为频道管理员）
- 填入配置：将获取的 Token 和 Chat ID 填入管理后台「通知设置」页面
- 大陆服务器反代：如果服务器无法直连 Telegram，可在「通知设置」里填写
Telegram API Base URL，例如 https://your-proxy.example.com，Metapi 将请求 https://your-proxy.example.com/bot<token>/sendMessage
- 测试：保存后点击页面上的「测试通知」按钮验证是否收到消息
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 |
运行时设置
管理后台「设置」中的运行时设置与环境变量分开管理：环境变量负责启动默认值；保存后的运行时设置会持久化到当前运行数据库，并覆盖对应默认值。
| 分类 |
对应项 |
生效方式 |
| 代理访问与网络 |
PROXY_TOKEN、SYSTEM_PROXY_URL、ADMIN_IP_ALLOWLIST |
保存后即时生效 |
| 定时任务 |
CHECKIN_CRON、BALANCE_REFRESH_CRON |
保存后即时生效 |
| 智能路由 |
ROUTING_FALLBACK_UNIT_COST、各路由权重 |
保存后即时生效 |
| 通知渠道 |
Webhook / Bark / Telegram / Server酱 / SMTP / NOTIFY_COOLDOWN_SEC |
保存后即时生效 |
| 数据库运行配置 |
DB_TYPE、DB_URL、DB_SSL |
保存后在下次 Metapi 后端启动时生效 |
TOKEN_ROUTER_CACHE_TTL_MS、PROXY_LOG_RETENTION_DAYS、PROXY_LOG_RETENTION_PRUNE_INTERVAL_MINUTES 当前仍属于部署级环境变量，不在后台运行时设置里单独维护。
下一步
