环境与配置

先把环境变量和部署差异理顺。

按基础配置、网关、支付和运维四块看，就能更快知道每个环境该填什么。

查看安全指南查看回调指南

API 文档/环境与配置

基础配置

数据库、鉴权和运行环境是整个平台最底层的三块配置。

先确认数据库可连、鉴权 secret 已按环境拆分，再继续接后面的网关、支付和巡检。

DATABASE_URL 决定整个平台的数据落点

钱包、订单、令牌、日志、后台统计都依赖数据库，所以数据库配置永远是第一优先级。

AUTH_SECRET 不该在不同环境混用

开发、测试、生产环境最好各用独立 secret，避免跨环境 session 污染和 Cookie 误复用。

NODE_ENV 会影响 Cookie 安全属性

生产环境会启用更严格的 secure Cookie 逻辑，因此 staging 和 production 的域名与协议需要提前规划好。

基础环境变量示例

DATABASE_URL="mysql://root:[email protected]:3306/token_ai"
AUTH_SECRET="replace-with-a-long-random-secret"

# Rate Limit
API_RATE_LIMIT_PER_MINUTE="6000"
API_RATE_LIMIT_PER_HOUR="60000"

网关配置

网关配置决定请求会不会真正发出去。

真实上游配置应在后台渠道管理逐条维护，不再建议通过环境变量提供全局 AI 网关。

多渠道时，优先去后台渠道管理为每条渠道填写 `Base URL` 和 `API Key`。
模型映射也应在渠道级维护，避免不同上游之间互相覆盖。
`CHANNEL_RUNTIME_AUTO_PROTECT` 建议在生产保持开启，让异常渠道自动进入保护状态并在恢复后重新参与调度。

网关与渠道保护配置

# 后台渠道管理中逐条维护：
# - Base URL
# - API Key
# - 模型映射
CHANNEL_RUNTIME_AUTO_PROTECT="true"
CHANNEL_HEALTH_TIMEOUT_MS="4000"
CHANNEL_HEALTH_LATENCY_SPIKE_MS="1800"

支付配置

支付配置最容易在“本地能用、线上回调不通”这里出问题。

支付建议分成模式、回调和回跳地址三部分看。上线前先确认这些地址都指向正式环境。

mock 模式适合前后台验证

创建订单后可以在充值页直接模拟支付。
这条链路仍然会真实写入订单、钱包和账本。

manual 模式适合第三方支付接入准备态

系统会生成支付页、回调示例和创建支付单参数预览。
正式支付对接前，至少要补齐回调鉴权配置。

支付回调域名必须和实际部署环境一致

`PAYMENT_NOTIFY_BASE_URL` 应指向第三方网关可以访问到的真实域名。
本地开发能跑通，不代表公网回调一定可达。

支付与回调配置示例

PAYMENT_PROVIDER_MODE="manual"
PAYMENT_RETURN_URL="https://your-web.example.com/console/recharge"
PAYMENT_NOTIFY_BASE_URL="https://your-user-api.example.com"
PAYMENT_MANUAL_INSTRUCTIONS="订单创建后请按真实支付流程完成转账|后续可由回调或后台确认到账"
PAYMENT_CALLBACK_TOKEN="replace-with-a-callback-secret"
PAYMENT_CALLBACK_SIGNING_SECRET=""
PAYMENT_CALLBACK_MAX_AGE_SECONDS="300"
PAYMENT_ALIPAY_GATEWAY_URL=""
PAYMENT_WXPAY_GATEWAY_URL=""
PAYMENT_STRIPE_GATEWAY_URL=""

运维与巡检

限流、巡检和 cron 这组配置更偏运维侧，但会直接影响平台稳定性。

这组配置决定系统能不能在出问题时自动收敛风险，生产环境建议单独记录和审查。

推荐重点关注

`API_RATE_LIMIT_PER_MINUTE` 和 `API_RATE_LIMIT_PER_HOUR` 控制对外接口的分钟 / 小时窗口。
`CHANNEL_HEALTH_TIMEOUT_MS`、`CHANNEL_HEALTH_LATENCY_SPIKE_MS` 控制巡检判定与运行时自动保护阈值。
生产环境的巡检与模型同步应由 `job-worker` 直接执行，不再依赖公开 HTTP cron 入口。

环境拆分建议

本地环境优先保证数据库、登录、示例数据和 mock 支付可用。
staging 环境优先验证真实 AI 网关、限流、渠道巡检和回调链路。
production 环境再打开正式域名、正式支付网关，并由 `job-worker` 承担定时任务。

job-worker 任务示例

CHANNEL_HEALTH_JOB_INTERVAL_MS="300000"
MODEL_SYNC_JOB_INTERVAL_MS="21600000"
MODEL_SYNC_REQUIRE_PRICE_APPROVAL="true"
MODEL_SYNC_MODEL_PAUSE_MS="150"
MODEL_SYNC_PROVIDER_PAUSE_MS="1000"

node --import tsx scripts/job-worker.mjs --once --job=channel-health
node --import tsx scripts/job-worker.mjs --once --job=model-sync

环境与配置

先把环境变量和部署差异理顺。

按基础配置、网关、支付和运维四块看，就能更快知道每个环境该填什么。

查看安全指南查看回调指南

API 文档/环境与配置

基础配置

数据库、鉴权和运行环境是整个平台最底层的三块配置。

先确认数据库可连、鉴权 secret 已按环境拆分，再继续接后面的网关、支付和巡检。

DATABASE_URL 决定整个平台的数据落点

钱包、订单、令牌、日志、后台统计都依赖数据库，所以数据库配置永远是第一优先级。

AUTH_SECRET 不该在不同环境混用

开发、测试、生产环境最好各用独立 secret，避免跨环境 session 污染和 Cookie 误复用。

NODE_ENV 会影响 Cookie 安全属性

生产环境会启用更严格的 secure Cookie 逻辑，因此 staging 和 production 的域名与协议需要提前规划好。

基础环境变量示例

DATABASE_URL="mysql://root:[email protected]:3306/token_ai"
AUTH_SECRET="replace-with-a-long-random-secret"

# Rate Limit
API_RATE_LIMIT_PER_MINUTE="6000"
API_RATE_LIMIT_PER_HOUR="60000"

网关配置

网关配置决定请求会不会真正发出去。

真实上游配置应在后台渠道管理逐条维护，不再建议通过环境变量提供全局 AI 网关。

多渠道时，优先去后台渠道管理为每条渠道填写 `Base URL` 和 `API Key`。
模型映射也应在渠道级维护，避免不同上游之间互相覆盖。
`CHANNEL_RUNTIME_AUTO_PROTECT` 建议在生产保持开启，让异常渠道自动进入保护状态并在恢复后重新参与调度。

网关与渠道保护配置

# 后台渠道管理中逐条维护：
# - Base URL
# - API Key
# - 模型映射
CHANNEL_RUNTIME_AUTO_PROTECT="true"
CHANNEL_HEALTH_TIMEOUT_MS="4000"
CHANNEL_HEALTH_LATENCY_SPIKE_MS="1800"

支付配置

支付配置最容易在“本地能用、线上回调不通”这里出问题。

支付建议分成模式、回调和回跳地址三部分看。上线前先确认这些地址都指向正式环境。

mock 模式适合前后台验证

创建订单后可以在充值页直接模拟支付。
这条链路仍然会真实写入订单、钱包和账本。

manual 模式适合第三方支付接入准备态

系统会生成支付页、回调示例和创建支付单参数预览。
正式支付对接前，至少要补齐回调鉴权配置。

支付回调域名必须和实际部署环境一致

`PAYMENT_NOTIFY_BASE_URL` 应指向第三方网关可以访问到的真实域名。
本地开发能跑通，不代表公网回调一定可达。

支付与回调配置示例

PAYMENT_PROVIDER_MODE="manual"
PAYMENT_RETURN_URL="https://your-web.example.com/console/recharge"
PAYMENT_NOTIFY_BASE_URL="https://your-user-api.example.com"
PAYMENT_MANUAL_INSTRUCTIONS="订单创建后请按真实支付流程完成转账|后续可由回调或后台确认到账"
PAYMENT_CALLBACK_TOKEN="replace-with-a-callback-secret"
PAYMENT_CALLBACK_SIGNING_SECRET=""
PAYMENT_CALLBACK_MAX_AGE_SECONDS="300"
PAYMENT_ALIPAY_GATEWAY_URL=""
PAYMENT_WXPAY_GATEWAY_URL=""
PAYMENT_STRIPE_GATEWAY_URL=""

运维与巡检

限流、巡检和 cron 这组配置更偏运维侧，但会直接影响平台稳定性。

这组配置决定系统能不能在出问题时自动收敛风险，生产环境建议单独记录和审查。

推荐重点关注

`API_RATE_LIMIT_PER_MINUTE` 和 `API_RATE_LIMIT_PER_HOUR` 控制对外接口的分钟 / 小时窗口。
`CHANNEL_HEALTH_TIMEOUT_MS`、`CHANNEL_HEALTH_LATENCY_SPIKE_MS` 控制巡检判定与运行时自动保护阈值。
生产环境的巡检与模型同步应由 `job-worker` 直接执行，不再依赖公开 HTTP cron 入口。

环境拆分建议

本地环境优先保证数据库、登录、示例数据和 mock 支付可用。
staging 环境优先验证真实 AI 网关、限流、渠道巡检和回调链路。
production 环境再打开正式域名、正式支付网关，并由 `job-worker` 承担定时任务。

job-worker 任务示例

CHANNEL_HEALTH_JOB_INTERVAL_MS="300000"
MODEL_SYNC_JOB_INTERVAL_MS="21600000"
MODEL_SYNC_REQUIRE_PRICE_APPROVAL="true"
MODEL_SYNC_MODEL_PAUSE_MS="150"
MODEL_SYNC_PROVIDER_PAUSE_MS="1000"

node --import tsx scripts/job-worker.mjs --once --job=channel-health
node --import tsx scripts/job-worker.mjs --once --job=model-sync

页面加载中

先把环境变量和部署差异理顺。

数据库、鉴权和运行环境是整个平台最底层的三块配置。

网关配置决定请求会不会真正发出去。

支付配置最容易在“本地能用、线上回调不通”这里出问题。

限流、巡检和 cron 这组配置更偏运维侧，但会直接影响平台稳定性。

先把环境变量和部署差异理顺。

数据库、鉴权和运行环境是整个平台最底层的三块配置。

网关配置决定请求会不会真正发出去。

支付配置最容易在“本地能用、线上回调不通”这里出问题。

限流、巡检和 cron 这组配置更偏运维侧，但会直接影响平台稳定性。