环境变量、日志与诊断

环境变量

Preview 与 Production 的变量相互隔离：

xdbapp env list
xdbapp env set API_TOKEN --scope preview
xdbapp env set API_TOKEN --scope production
xdbapp env unset API_TOKEN --scope preview --yes

env set 默认隐藏输入，适合人工录入密钥。AI 或 CI 可以从标准输入传值，避免出现在命令历史：

printf '%s' "$API_TOKEN" | xdbapp env set API_TOKEN --scope production --stdin

批量导入：

xdbapp env import .env.preview --scope preview

平台不会再次通过 env list 返回环境变量的值，只会显示变量名等非敏感信息。Preview 新值会在下一次 xdbapp dev 启动或 Preview 发布时加载；Production 新值在下一次 Promote / Rollback 时加载。已经运行的进程不会在中途自动改变环境变量。

商家管理员也可以在信多帮后台进入“云应用 → 管理设置 → 运行环境变量”，分别新增或删除 Preview / Production 变量。页面保存后只显示变量名、环境和更新时间，不回显值。CLI 与后台管理的是同一份配置；不需要重复设置。

不要自行设置平台保留的 XDB_PAAS_*、XDB_OPEN_*、DATABASE_URL 和 PORT。

其中 XDB_OPEN_APP_ID、XDB_OPEN_APP_SECRET 是平台托管变量：云应用创建时自动生成专属凭据，Preview/Production 容器启动时由平台自动注入；本地 xdbapp dev -- <启动命令> 使用回环代理提供短期 Token，不会下发长期 AppSecret。它们不应使用 env set 手工维护，也不应写入 .env。

构建期公开变量

普通 Preview/Production 变量只进入 Runtime，不会提供给 Builder。确实需要参与前端编译或镜像构建的公开配置，必须使用受限前缀并明确增加 --public：

printf '%s' 'https://api.example.test' | xdbapp env set VITE_PUBLIC_API_BASE --scope build --public --stdin

允许的前缀是 PUBLIC_、VITE_、NEXT_PUBLIC_、NUXT_PUBLIC_。构建变量可能进入浏览器资源或镜像层，不能保存密码、Token、AppSecret 等敏感内容。

构建日志

xdbapp logs --deployment <deployment-id> --type build --since 30m

构建日志用于排查依赖安装、编译、migration 和健康检查错误。

运行日志

xdbapp logs --environment production --type runtime --follow

--follow 持续显示新日志，按 Ctrl+C 停止。应用自身也应避免把密码、Token、身份证号等敏感内容写入日志。

平台会持续归档当前 Runtime 的标准输出和错误输出。即使容器因发布、回滚、健康修复或 ECS 重启被替换，已归档日志仍可按 Deployment 查询。单个 Deployment 达到容量上限后会滚动保留最新内容；Deployment 超过平台版本保留期后，日志随该版本一起清理。

综合诊断

xdbapp doctor

它会检查 CLI 版本、当前登录、项目关联、配置文件和平台连通性，不会修改代码或发布应用。

需要提供给技术支持时，可以使用 JSON 输出：

xdbapp doctor --json