125 lines
9.2 KiB
Markdown
125 lines
9.2 KiB
Markdown
# 踩坑与排障记录
|
||
|
||
> 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
|
||
|
||
## 记录格式
|
||
|
||
```md
|
||
## 问题标题
|
||
|
||
- 现象：看到什么错误或异常行为
|
||
- 原因：确认后的根因
|
||
- 处理：具体修复步骤
|
||
- 验证：如何确认修复有效
|
||
- 关联：相关文件、文档、提交或 Issue
|
||
```
|
||
|
||
## OSS V4 签名时间和 bucket/object_key 兼容
|
||
|
||
- 现象：OSS V4 私有读签名在部分时间点失败，可能出现 `OSS V4 签名时间格式化失败` 或服务端判定签名格式错误；排查用例中 bucket 为 `xushi-dev`，object_key 为 `generated-square-hole-assets/.../image.png`。
|
||
- 原因：旧逻辑依赖 `time::Time::to_string()` 再去掉冒号，小时小于 10 时输出不稳定补零；同时排查时容易把 bucket 名误当成 object_key 的一部分。
|
||
- 处理：OSS V4 `x-oss-date` 使用固定宽度 `yyyyMMdd'T'HHmmss'Z'` 格式化；调用读签名或 `HEAD Object` 时只传 object_key，不要传 `bucket/object_key` 拼接路径。
|
||
- 验证：运行 `cd server-rs && cargo test -p platform-oss -- --nocapture`，并用 bucket=`xushi-dev`、object_key=`generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png` 覆盖签名生成。
|
||
- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/platform-oss/README.md`。
|
||
|
||
## 中文乱码与编码风险
|
||
|
||
- 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
|
||
- 原因：Windows/PowerShell/终端编码不一致，或整文件重写导致编码变化。
|
||
- 处理：
|
||
- 不要直接沿用乱码文本。
|
||
- 不要用英文替换中文，除非用户明确要求翻译。
|
||
- 在 PowerShell 5.1 中显式使用 UTF-8。
|
||
- 优先用 Python/Node 或 `Get-Content -Encoding UTF8` 核对原文。
|
||
- 修改中文文件时优先局部补丁，避免无关内容重写。
|
||
- 验证：运行仓库已有编码检查；人工抽查修改文件中的中文内容。
|
||
- 关联：`AGENTS.md`、`npm run check:encoding`。
|
||
|
||
## `.hermes` 只放共享内容，不放个人 Hermes 配置
|
||
|
||
- 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
|
||
- 原因：仓库 `.hermes/` 与个人 `~/.hermes/` 名称相似。
|
||
- 处理：仓库 `.hermes/` 只放 Markdown 共享记忆、计划和可公开 skills；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。
|
||
- 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
|
||
- 关联：`.hermes/README.md`。
|
||
|
||
## 旧后端路线文档造成判断漂移
|
||
|
||
- 现象：开发时参考到 Express、Node、PostgreSQL 或 Go 方向旧文档，导致接口、数据真相或部署路径与当前主线不一致。
|
||
- 原因：项目历史文档较多，部分旧方案仍保留作迁移参考。
|
||
- 处理：涉及服务端、数据真相、SpacetimeDB、运行时状态时，先看 `CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`，再看 DDD 总纲和具体技术方案。
|
||
- 验证：代码改动应落在 `server-rs + Axum + SpacetimeDB` 主线；旧路线只作为迁移参考，不作为兼容目标。
|
||
- 关联：`docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`、`AGENTS.md`。
|
||
|
||
## SpacetimeDB 表结构变更不能按 PostgreSQL 迁移直觉处理
|
||
|
||
- 现象：发布时 schema 冲突、自动迁移拒绝、旧客户端调用 reducer 失败、private 表数据迁移遗漏。
|
||
- 原因：SpacetimeDB 对字段删除、类型变化、索引/主键/RLS/reducer 变化有不同自动迁移边界。
|
||
- 处理：变更前阅读 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`；涉及表变化时同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 bindings；必要时走 JSON 导入导出与分片导入迁移流程。
|
||
- 验证：发布前完成 schema 检查、bindings 生成、表目录更新和相关 smoke。
|
||
- 关联：`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
|
||
|
||
## 本地 SpacetimeDB replica identity 不匹配
|
||
|
||
- 现象：本地 standalone 启动时报 `mismatched database identity`。
|
||
- 原因：root-dir / replica 数据残留与当前数据库身份不一致。
|
||
- 处理：按本地 replica identity mismatch 文档进行备份、重建和脚本诊断。
|
||
- 验证：本地 SpacetimeDB 可正常启动并 publish / 访问。
|
||
- 关联：`docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md`。
|
||
|
||
## Vite SPA fallback 吞掉 API 请求
|
||
|
||
- 现象：本地请求 `/api/profile/*` 等接口时返回 HTML，被前端当 JSON 解析报错。
|
||
- 原因：Vite 代理缺少对应 `/api/*` 前缀，API 请求落到 SPA fallback。
|
||
- 处理：补齐 Vite 代理，让 API 请求转发到 Rust `api-server`。
|
||
- 验证：请求返回 JSON，相关页面不再出现 HTML parse 错误。
|
||
- 关联：`docs/technical/PROFILE_MAIN_ROUTE_VITE_PROXY_FIX_2026-05-02.md`。
|
||
|
||
## 反馈页清空 file input 前必须先拷贝 FileList
|
||
|
||
- 现象：点击上传凭证会打开文件选择框，但选择图片后页面没有展示预览，提交时也没有携带图片凭证。
|
||
- 原因：浏览器传入的 `FileList` 可能跟 `<input type="file">` 保持 live 绑定；如果先执行 `input.value = ''`，再从参数里的 `FileList` 读取文件，列表可能已经为空。
|
||
- 处理：在清空 file input 前先执行 `const selectedFiles = files ? Array.from(files) : []`，后续图片类型、大小、Data URL 读取和预览都基于这个普通数组。
|
||
- 验证：`PlatformFeedbackView.test.tsx` 用 mock `FileReader` 断言选择图片后出现 `反馈凭证预览`，且提交 payload 带 `evidenceItems[].dataUrl`。
|
||
- 关联：`src/components/platform-entry/PlatformFeedbackView.tsx`、`docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md`。
|
||
|
||
## 拼图 APIMart 图片生成密钥不能复用 DashScope / ARK key
|
||
|
||
- 现象：拼图新手引导或拼图创作点击生成后返回 `APIMart 图片生成密钥未配置`。
|
||
- 原因：拼图 `gpt-image-2` / `nanobanana2` 图片生成已按技术方案统一走 APIMart；后端只读取 `APIMART_BASE_URL`、`APIMART_API_KEY`、`APIMART_IMAGE_REQUEST_TIMEOUT_MS`，不会用 `DASHSCOPE_API_KEY`、`LLM_API_KEY` 或 `ARK_API_KEY` 兜底。
|
||
- 处理：在本机私密配置 `.env.secrets.local` 或进程环境中配置真实 `APIMART_API_KEY`，不要提交到 Git；填入后必须重启 `api-server` / `npm run dev`，运行中的进程不会自动加载新 env。
|
||
- 验证：不打印密钥内容，只检查 `APIMART_API_KEY` 非空；重启后触发拼图生成不再返回本地配置缺失的 503。
|
||
- 关联：`docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md`、`.codex/skills/gpt-image-2-apimart/SKILL.md`。
|
||
|
||
## Rust 冷编译导致 api-server 健康检查误超时
|
||
|
||
- 现象：`npm run dev:rust` 在 Windows 冷编译/链接阶段误判 `/healthz` 等待超时并杀掉 `cargo run`。
|
||
- 原因：脚本把 SpacetimeDB 与 api-server 等待窗口混在一起，未考虑 Rust 冷编译耗时。
|
||
- 处理：按冷编译超时修复文档拆分等待窗口。
|
||
- 验证：冷启动时不再误杀仍在编译的 api-server。
|
||
- 关联：`docs/technical/API_SERVER_DEV_STACK_COLD_BUILD_TIMEOUT_FIX_2026-04-25.md`。
|
||
|
||
## server-rs 默认 cargo build 不能等同于构建 SpacetimeDB 模块
|
||
|
||
- 现象：在 `server-rs` 下无参数 `cargo build` 期望同时构建 `spacetime-module`，导致链接或构建范围误判。
|
||
- 原因：workspace default-members 当前只包含 `crates/api-server`；SpacetimeDB module 有独立构建/发布方式。
|
||
- 处理：默认 Rust 构建只覆盖原生 `api-server`；模块产物继续走 `spacetime build` / publish / bindings 生成流程。
|
||
- 验证：查看 `server-rs/Cargo.toml` default-members，并按相关 SpacetimeDB 文档执行模块构建。
|
||
- 关联：`server-rs/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md`。
|
||
|
||
## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本
|
||
|
||
- 现象：部署、回滚或 Jenkins Job 重建时参考旧发布文档，导致 systemd、Nginx、SpacetimeDB 自托管和生产包拆分不一致。
|
||
- 原因：旧 Jenkins / 旧本地远端部署脚本文档仍作为历史经验保留。
|
||
- 处理：生产相关操作先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`，再按需追溯旧文档。
|
||
- 验证：发布链路使用当前 `deploy/systemd`、`deploy/nginx`、`scripts/deploy` 和 `jenkins/Jenkinsfile.production-*`。
|
||
- 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
|
||
|
||
## 个人任务 scope 不得扩成 work/site/module
|
||
|
||
- 现象：个人任务配置为 `work` / `site` / `module` 后进度串桶或静默按 0 处理。
|
||
- 原因：首版个人任务只支持用户维度，非 user scope 会造成任务进度读取语义错误。
|
||
- 处理：Admin 任务配置页不展示范围选择，保存时固定 `scopeKind: 'user'`；API 和领域构造层拒绝非 `User`。
|
||
- 验证：非 `user` scope 返回错误；相关测试覆盖 `Site` / `Module` / `Work` 被拒绝。
|
||
- 关联：`docs/technical/RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md`、`docs/technical/ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md`。
|