Echo Nebula Feedback 文档

故障排查

目标读者：排查本地 Alpha 环境、SDK payload 和 API 调用的开发者。

从失败边界开始定位：Godot payload 生成、本地队列、public API、附件上传、admin API 认证，或 Docker Compose 依赖。

最小示例

cd ../echo-nebula-infra
./scripts/smoke-public-api.sh
./scripts/smoke-admin-api.sh

curl -i "http://localhost:4100/healthz"
curl -i "http://localhost:4100/readyz"
curl -i "http://localhost:4000/healthz"
curl -i "http://localhost:4000/readyz"

curl -fsS "http://localhost:4000/v1/sdk/config?locale=zh-CN" \
  -H "X-Project-Key: enb_pk_xxx"

仅使用 feedback_payload_ready 观察准备状态和字段数量，参见第一条反馈。该信号不证明已送达。可在本机核对队列条目数量、HTTP 状态、稳定错误码和响应关联 ID，并在 Developer Console 确认报告与附件。不要打印或附上传完整 payload、队列 JSON、描述、联系方式、日志、Key、token 或签名 URL。提交 consent 不代表允许将玩家数据复制到诊断日志。

应区别对待 /healthz 和 /readyz。健康检查成功只说明进程存活，并不说明 PostgreSQL 或对象存储可用。Admin 返回 200 degraded 表示 PostgreSQL 已就绪而对象存储降级；文本管理可继续，但附件操作可能失败。Public 要求两个依赖都可用，任一失败都会返回 503 unavailable。需要可重复的故障与恢复证据时，使用 ./scripts/e2e-readiness-isolated.sh，不要操作默认 Compose project。

常见错误

下一步

回到 Alpha 概览 检查端到端顺序。

资源与配置边界

Public config 读取和两个写入口共用进程内、鉴权前的连接来源 IP 预算，默认每分钟 600 次；缺失或无效 Project Key 同样计入。鉴权后的写入另有项目预算，默认每分钟 60 次，同项目的 Key 共用。429 使用 common.rate_limited 和 Retry-After，应等待后重试。不信任 Forwarded/X-Forwarded-For；代理转发的流量共用代理 IP 预算，部署时须在入口限制实际客户端并配置服务预算。计数不跨副本共享。每个 limiter 最多保留 4096 个活动身份；满额时拒绝新身份，过期后恢复容量。

附件文件名必须是有效 UTF-8、1–255 个 Unicode 码点且不含控制字符，basename 不能是点或双点；违规返回 400 attachment.invalid。移除路径部分，不支持的字符在保存名称中变为下划线。文件内容仍受契约 10 MiB 上限和部署的更小限制约束。文件名拒绝时不创建对象，重试继续遵守 consent、项目隔离与幂等规则。

Admin JSON 请求体上限为 64 KiB，认证/组织原有 16 KiB 上限保留。过大、不完整或非法 JSON 使用原有路由对应的 400 错误。反馈 search 在 trim 前最多 200 个 Unicode 码点；无效 UTF-8 或超长输入返回 400 admin.request.invalid。UI 也按码点验证。

两个 API 启动时拒绝格式错误、零、负值或过大的资源配置。Public 的请求头/读取/写入/空闲/退出超时默认为 5s/2m/2m/2m/10s；Admin 为 5s/15s/30s/1m/10s。超时必须为正：请求头/退出至多 1m，读取/写入/空闲至多 5m，readiness 至多 30s。限流窗口为正且至多 1h，次数为 1–1,000,000。下载 TTL 为正且至多 1h，默认 15m。Public 反馈体字节范围 1–1,048,576，附件字节 1–10,485,760，日志条数 1–200，breadcrumb 1–100，联系方式字符 1–200；关闭可选数据应使用项目 feature flag。

非 APP_ENV=local 必须显式配置 DATABASE_URL、S3_ENDPOINT、S3_REGION、S3_BUCKET 和非默认 S3 凭证；数据库密码和 S3 secret 至少 16 字节。PostgreSQL 使用 URI 和唯一、显式的 sslmode；公网主机要求 verify-full，私网 IP、单段服务名及 .internal/.localhost 主机可在受控网络使用 disable、require 或 verify-ca。query 不能覆盖数据库身份、主机或凭证。S3 仅上述私网主机允许 HTTP，其余要求 HTTPS。Admin 另要求 HTTPS S3_PUBLIC_ENDPOINT、非默认强 JWT/bootstrap 凭证，以及显式浏览器 CORS allowlist 中的 HTTPS origin。空 CORS 列表不开放跨源浏览器访问。local 默认值仍可用，不应复用于非 local。配置错误只标明字段，不输出值。这些检查不代表已生产部署或具备多副本限流。