﻿P10-14 为"升级服务器 + 数据迁移"做前置准备（长期打算）

## 用户意图（2026-10-20 10:05）
「做好后续需要调整的准备，如果功能足够强大了，我会升级服务器，后续就可能需要迁移数据。
这些前置工作都可以准备起来。我们要做长期打算。」

## 一、原则：一切可搬走（不要写死）
现在必须改成"数据与代码分离、路径可配置"，否则将来迁移会很痛。

### 1) 路径不再硬编码
- 新建 `config\cloud_paths.json`（本地）与服务器 `C:\nxai-cloud\paths.json`：
```json
{
  "root": "C:/nxai-cloud",
  "memory": "memory",
  "inbox": "inbox",
  "outbox": "outbox",
  "archive": "archive",
  "log": "log",
  "state_db": "state.sqlite3"
}
```
- 所有脚本从该文件读根目录，**禁止再出现字面量 `C:\nxai-cloud`**（除读取该配置处外）。
- 迁移时只改这一个文件即可换根目录。

### 2) 数据全部可导出/可导入
新建 `tools\cloud_export.py` / `tools\cloud_import.py`：
```
cloud_export.py --out D:\backup\nxai-cloud-<日期>.zip [--include files,memory,index,state]
cloud_import.py --zip <包> [--target-root <新路径>] [--dry-run]
```
- 导出包内含 `MANIFEST.json`：文件清单、size、sha256、导出时间、schema 版本
- 导入时逐文件校验 sha256，任何不匹配即中止并报告（不许半途而废）
- 导入前后各打印一次文件数与总字节数

### 3) Schema 版本化
- `state.sqlite3` 里建 `meta(schema_version, created_at, app_version)` 表
- 新建 `tools\cloud_migrate.py`：按 schema_version 顺序执行迁移步骤，
  每步前自动备份，失败即回滚并打印原因
- 当前版本记为 1；以后每次结构变化 +1

### 4) 配置与凭据分离
- 服务器配置（端口、并发、资源上限）放 `config\server_profile.json`：
```json
{"profile":"small","mem_mb":2048,"max_concurrency":1,"poll_sec":30,"max_parallel_tasks":1}
```
- **profile 可切换**：`small`(2GB, 串行) / `large`(8GB+, 并发2, 轮询10s)
  将来升级服务器只需把 profile 改成 large，不用改代码
- 凭据只在本机 DPAPI，**永不进导出包**（导出时显式排除 `*_pwd*`、`*token*`、`*.dpapi`）

### 5) 每日备份（轻量，适合 2GB）
- 服务器侧 cron/计划任务：每天把 `memory/`、`index.json`、`state.sqlite3`
  打包到 `archive\backup\<日期>.zip`，保留最近 7 份，旧的删
- 备份包 ≤ 50MB（只备份元数据与经验，不备份 NC 大文件；NC 进 outbox 后 7 天清理）
- 备份结果写 `log\backup.log`，失败要能看出来

## 二、迁移演练（必须做一次，别等真出事）
`tools\cloud_export.py` 导出 → 在本地另一个目录 `cloud_import.py` 导入 →
比对文件数与 sha256 全一致。**这次演练通过后才算本卡完成**。

## 三、文档
`docs\15_迁移手册.md` 写清：
- 新服务器要装什么（Python 版本、路径、Hermes 是否要重装）
- 迁移步骤（停 worker → 导出 → 传包 → 导入 → 改 paths.json → 起 worker → 验证）
- 回滚步骤
- 2GB → 8GB 升级后要改的 profile 与并发
- 已知依赖（Hermes 目录位置、nginx 配置、QQ 网关配置在哪）

## 四、验收（实测）
1. `cloud_paths.json` 生效证据：把 root 改成临时目录再跑一次，证明能正常创建四个子目录
2. 代码里搜不到硬编码 `C:\nxai-cloud`（除配置读取处），贴出搜索命令与结果
3. 导出→导入演练：贴出两边文件数与 sha256 校验一致的输出
4. `cloud_migrate.py` 对 schema v1 跑一次，贴出 meta 表内容
5. 导出包内**不含**任何密码/token（贴出 zip 文件名列表，证明已排除）
6. 备份任务实跑一次，贴出 zip 路径与大小
7. 门禁全绿 + 新增 .py 含 `P2-02 控制台编码护栏`

## 约束
- 不改 Hermes 核心；不装软件
- 导出包不含凭据
- 完成后写 `状态\P10-14.done.json`
