docs(37): 补「换到新环境必须先做」的前置清单（建集合/Milvus/embedding 端点/迁移）

2026-09-12 14:35:49 +08:00
parent c12f836d26
commit b2a2e4292b
1 changed files with 15 additions and 0 deletions
@@ -82,6 +82,21 @@
 建集合：`python tools/setup_milvus_profile_collection.py`
 ——**幂等**，集合已存在时只做结构比对报告、不覆盖不删重建（共享 Milvus 实例里还有别的项目的集合）。

+> ## ⚠️ 换到新环境（例如最终验收在架构师机器上跑）必须先做这一步
+>
+> **集合是环境数据，不随代码合并。** 本线的代码里没有、也不该有"自动建集合"的逻辑
+> （那会让"环境没准备好"被静默盖住）。所以在新机器上：
+
+| 前置 | 命令 | 不做的后果 |
+|---|---|---|
+| **建画像向量集合** | `python -X utf8 tools/setup_milvus_profile_collection.py` | `load_collection` 抛 `RecoverableAgentError("画像向量集合不可用")` ⇒ `memory_sync_outbox` 的 `milvus` 行**失败重试到死信**。**这是环境问题，不是代码缺陷** |
+| Milvus 可达 | `docker ps` 能看到 `milvus-standalone` 且 healthy | 同上；另注意 `MILVUS_LOCAL_URI` 若被设过会指向本地 Lite 文件、查的是另一个库 |
+| embedding 端点 | 发布配置里有 `task_type=embedding` 的端点 | `_profile_embed` 抛"没有可用的 embedding 端点"，事件同样重试到死信 |
+| 数据库迁移 | `alembic upgrade heads` | `memory_sync_outbox` / `memory_unit` 等表不存在 |
+
+> 建集合后可用 `python -X utf8 tools/setup_milvus_profile_collection.py` **再跑一次**确认输出为
+> `exists`（幂等，不会重复建）。
+
 ### `memory_sources` 契约（适配器的输入）

 ```json