103 lines
6.3 KiB
Markdown
103 lines
6.3 KiB
Markdown
# 踩坑与排障记录
|
||
|
||
> 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
|
||
|
||
## 记录格式
|
||
|
||
```md
|
||
## 问题标题
|
||
|
||
- 现象：看到什么错误或异常行为
|
||
- 原因：确认后的根因
|
||
- 处理：具体修复步骤
|
||
- 验证：如何确认修复有效
|
||
- 关联：相关文件、文档、提交或 Issue
|
||
```
|
||
|
||
---
|
||
|
||
## 中文乱码与编码风险
|
||
|
||
- 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
|
||
- 原因：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`。
|
||
|
||
## 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`。
|