运行时变量与绑定

配置统一保存在 apps/api/.env，从 apps/api/.env.example 复制。使用下列变量名；NODE_ENV 决定运行模式。生产密钥使用受保护环境或 Workers secrets。

名称	用途、默认与限制
ADMIN_HOST	用途、默认与限制可选独立后台主机名；默认主站 /admin。
AI	用途、默认与限制可选 Workers AI 翻译绑定，未配置时跳过该提供商。
ASN_DATABASE_PATH	用途、默认与限制仅自托管：运营方维护的 GeoLite2-ASN/IPinfo Lite MMDB 路径（最大 128 MiB）；启动加载，每 30 秒检查变更，更新失败保留旧库；未配置时 ASN 为 null 并在启动记录一次。
ASSETS	用途、默认与限制门户与后台静态资源绑定；不是本站的部署目录。
CLIENT_IP_HEADER	用途、默认与限制自托管可选可信代理覆盖的单个 IP 字面量头；未设置时使用 socket 地址，非法或缺失的可信头按未知处理。Workers 使用 cf-connecting-ip。
DATABASE_URL	用途、默认与限制自托管或迁移直连 PostgreSQL；生产使用 TLS。Workers API 使用 Hyperdrive。
DB_POOL_MAX	用途、默认与限制自托管 PostgreSQL 连接池上限，默认 20，正整数。
EMAIL	用途、默认与限制可选 Email Service 绑定；在目标账户验证可用性。
FILES_PRIVATE	用途、默认与限制私有 R2 桶；禁止 r2.dev、公开域名与匿名读取。
FILES_PUBLIC	用途、默认与限制公开 R2 桶；上传功能需要，可绑定公开域名。
HOST	用途、默认与限制Bun 监听地址，默认 127.0.0.1；容器显式设 0.0.0.0。
HYPERDRIVE	用途、默认与限制Workers PostgreSQL 绑定，必填；关闭查询缓存，迁移绕过它。
INSTALL_TOKEN	用途、默认与限制安装向导的 secret：生产环境未设置时拒绝安装；设置后任何模式下都必须输入同一个值才会创建 root 账户。安装完成后可删除。
JOB_NOTIFY_QUEUE	用途、默认与限制可选通知类任务门铃 Queue（验证码、用户通知）；未配置时使用 JOB_QUEUE。
JOB_QUEUE	用途、默认与限制可选任务门铃 Queue；提交后投递到期任务 ID，未配置时请求内用 waitUntil 加速，Cron 照常兜底。
LOG_DIR	用途、默认与限制仅自托管：可选私有 JSONL 日志目录，每个进程独占一个目录；stdout 仍输出。拒绝符号链接，查询只读。
LOG_INSTANCE_ID	用途、默认与限制日志实例标识，1–128 位字母、数字或 ._:-，默认进程随机 UUID；副本应设置不同的稳定值。
LOG_MAX_BYTES	用途、默认与限制每个日志文件的字节上限，默认 52428800（50 MiB），范围 256–104857600；超过 64 KiB 或文件上限的单行只输出到控制台。
LOG_MAX_FILES	用途、默认与限制日志文件总数（含当前文件），默认 10，范围 1–100；轮转和重启时删除最旧文件。
LOG_WORKERS_ACCOUNT_ID	用途、默认与限制可选 Workers Logs 仪表盘账户 ID，32 位小写十六进制；与 LOG_WORKERS_SCRIPT_NAME 同时配置，不含 API 令牌。
LOG_WORKERS_SCRIPT_NAME	用途、默认与限制可选 Workers 脚本名，1–63 位字母、数字、下划线或短横线；仅用于仪表盘链接，筛选预填需核对。
MASTER_KEYS	用途、默认与限制必填 secret，多版本主密钥环（v2:…,v1:…）；离线保留两份。
METRICS_TOKEN_HASH	用途、默认与限制可选 secret，metrics Bearer 令牌 SHA-256 的 64 位十六进制摘要；缺失/非法均拒绝。
NODE_ENV	用途、默认与限制development/test 启用全量响应校验，其余值按 production；Bun/Node 读取进程环境，Wrangler 构建时替换。
OUTBOUND_ALLOW_PRIVATE_CIDRS	用途、默认与限制仅自托管：允许 HTTPS 出站访问所列私网的精确 IPv4/IPv6 CIDR（逗号分隔，最多 256 项，默认空）；网络地址不得包含主机位，非法值启动失败。全部 DNS 地址必须通过策略；仍校验证书并拒绝重定向。不是后台设置。
REDIS_ALLOW_PLAINTEXT	用途、默认与限制1 允许非本机明文 Redis，仅受信私网；默认拒绝。
REDIS_URL	用途、默认与限制可选 Redis URL；非本机需 rediss://；不支持 Cluster/Sentinel。
SITE_HOSTS	用途、默认与限制主站/Origin 允许主机列表，逗号分隔，非默认端口需保留；生产必填。
STATE	用途、默认与限制StateShard Durable Object 命名空间；选择 do 时必填。
STATE_LOCATION	用途、默认与限制DO 位置提示，应靠近数据库；对象创建后位置固定。
STATE_SHARDS	用途、默认与限制默认 16；修改会重置令牌和限流所在分片。
SUBSCRIPTION_HOSTS	用途、默认与限制可选订阅专用主机列表，只提供 /s/*。
TRUSTED_PROXY_CIDRS	用途、默认与限制仅自托管：允许提供 CLIENT_IP_HEADER 的 socket 对端 CIDR，逗号分隔 IPv4/IPv6，最多 256 项；非法值启动失败，未设置时需由防火墙保证代理独占访问。
USER_LIST_SNAPSHOT_MAX_BYTES	用途、默认与限制增量用户基线单值上限（UTF-8 字节），默认 1048576，范围 1024–1900000；超过上限返回全量。
VALKEY_URL	用途、默认与限制Redis URL 未设置时的 Valkey 替代项，安全规则相同。
VOLATILE_STORE	用途、默认与限制auto/do/redis，默认 auto；Workers→do，自托管必须配置 Redis/Valkey。

Wrangler 配置项复制标题链接

配置	要求
compatibility_date	要求固定兼容日期，验证 nodejs_compat。
placement.mode	要求smart：让 Worker 靠近 PostgreSQL 运行，并测量实际延迟。
triggers.crons	要求* * * * * + 0 * * * *
migrations	要求StateShard 使用 new_sqlite_classes；保留已发布迁移历史。
assets / run_worker_first	要求保留 API、订阅和后台回退规则。

本地工具与发布复制标题链接

名称	用途
PG_CONTAINER / REDIS_CONTAINER	用途默认本地容器 ppanel-edge-pg / ppanel-edge-redis。
DEV_DB	用途本地开发库，默认 ppanel_edge。
CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID	用途发布所需 GitHub Environment secrets。
MIGRATOR_DATABASE_URL	用途发布 secret，仅迁移步骤作为 DATABASE_URL 注入。
SITE_URL	用途部署后烟测目标，不带凭据。

桶凭证、SMTP、渠道和翻译提供商在后台设置域配置，不是部署变量。