ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
108 lines
5.2 KiB
Markdown
108 lines
5.2 KiB
Markdown
# AI沟通记录：02-云同步链路问题分析
|
||
|
||
- **日期**：2026-06-21
|
||
- **参与者**：用户、AI 助手
|
||
- **会话序号**：02
|
||
|
||
## 讨论主题
|
||
|
||
用户反馈云同步（CloudSync）存在问题，对完整链路进行分析定位根因。
|
||
|
||
## 关键决策
|
||
|
||
无（本次为问题分析，未涉及改动决策）。
|
||
|
||
## 待办事项
|
||
|
||
- [ ] 配置 MAUI 端 `CloudSyncUrl` 指向 Host 地址（通过 UI 或配置文件）
|
||
- [ ] 考虑在 dev 模式下默认配置合理值，降低首次使用门槛
|
||
|
||
---
|
||
|
||
## 详细记录
|
||
|
||
### 01-当前运行环境
|
||
|
||
启动了三个服务：
|
||
|
||
| 服务 | 端口 | 终端 | 说明 |
|
||
|---|---|---|---|
|
||
| Vite dev server | 5174 | terminal 2 | `npm run dev`，proxy `/api` → `http://localhost:5057` |
|
||
| Host | 5173 | terminal 4 | `dotnet run src/Hua.Todo.Host`，完整 CloudSync 端点（`AddCloudSyncServer`） |
|
||
| MAUI (Windows) | 5057 | terminal 5 | `dotnet run src/Hua.Todo.Maui`，内嵌 WebServer，仅有 CloudSync 代理（`AddCloudSyncProxy`） |
|
||
|
||
### 02-云同步请求链路（当前状态）
|
||
|
||
```
|
||
Browser (localhost:5174)
|
||
│ POST /api/auth/login
|
||
│ GET /api/tasks/
|
||
│ POST /api/tasks
|
||
│ GET /api/security/policy
|
||
│ POST /api/cloud-sync/probe
|
||
▼
|
||
Vite dev server (5174)
|
||
│ vite.config.ts: proxy '/api' → target: 'http://localhost:5057'
|
||
▼
|
||
MAUI 内嵌 WebServer (5057)
|
||
│ UseCloudSyncProxy() 中间件拦截路径：
|
||
│ /api/auth, /api/tasks, /api/sync, /api/security, /api/cloud-sync
|
||
│
|
||
├─ CloudSyncUrl 已配置 → 代理转发到 Host(5173) → ✓ 正常
|
||
└─ CloudSyncUrl 为空 → 直接返回 503 → ✗ 当前状态
|
||
```
|
||
|
||
### 03-根因定位
|
||
|
||
**MAUI 的 `appsettings.json` 中未配置 `CloudSyncUrl`**。
|
||
|
||
- [appsettings.json](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Maui/appsettings.json) 中 `WebServer` 节点缺少 `CloudSyncUrl` 字段
|
||
- `CloudSyncProxyService.CloudSyncUrl` 默认值为空字符串，setter 中 `string.IsNullOrWhiteSpace` 将其转为 `null`
|
||
- [CloudSyncProxyService.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/Services/CloudSync/Services/CloudSyncProxyService.cs#L142-L148) 在 `UseCloudSyncProxy` 中间件中，`CloudSyncUrl` 为空时直接返回 **503 "cloud sync server URL not configured"**
|
||
|
||
### 04-本地 Todo API 不受影响
|
||
|
||
`/api/task`（本地 Todo CRUD）不在 CloudSyncProxy 的 `ProxyPathRoots` 中，由 `UseDynamicApi()` 直接处理，走 MAUI 本地 SQLite，正常工作。
|
||
|
||
### 05-完整架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 请求路径分流 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ /api/task/* ──────────→ DynamicApi (MAUI 本地) → MAUI SQLite │
|
||
│ (本地 Todo CRUD) ✓ 正常 │
|
||
│ │
|
||
│ /api/auth/* UseCloudSyncProxy 拦截 │
|
||
│ /api/tasks/* ├─ CloudSyncUrl 为空 → 503 ✗ │
|
||
│ /api/security/* └─ CloudSyncUrl 已配 → 转发 Host ✓ │
|
||
│ /api/cloud-sync/* │
|
||
│ │
|
||
│ /api/cloudSyncProxySettings ──→ DynamicApi (MAUI 本地) │
|
||
│ (设置 CloudSyncUrl 用) ✓ 正常 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 06-修复方案
|
||
|
||
**方案一（推荐，已有 UI 支持）**：通过 CloudSyncSettingsDialog 配置
|
||
1. 打开云同步设置弹窗
|
||
2. 输入服务端地址：`http://localhost:5173`
|
||
3. 点击"保存并探测"
|
||
4. 后续云同步请求经 MAUI 代理→Host，链路贯通
|
||
|
||
**方案二**：直接修改 MAUI 的 `appsettings.json`
|
||
在 `WebServer` 节点添加：`"CloudSyncUrl": "http://localhost:5173"`
|
||
|
||
**方案三**（纯 dev 模式）：切换 Vite proxy 目标
|
||
设置环境变量 `VITE_API_TARGET=http://localhost:5173`，让 Vite 直连 Host，绕过 MAUI 内嵌服务器。
|
||
注意：此模式下 Todo CRUD 走 Host 的 DB（`src/Hua.Todo.Host/Hua.Todo.db`），而非 MAUI 的本地 DB。
|
||
|
||
### 07-设计层面的潜在改进点
|
||
|
||
1. **默认值优化**：在 dev 模式下，`CloudSyncUrl` 可默认指向 `http://localhost:5173`（Host 默认端口），减少首次手动配置。
|
||
2. **错误提示增强**：503 响应可携带更友好的错误信息，前端弹窗提示用户去云同步设置中配置服务端地址。
|
||
3. **端口冲突风险**：当 Host(5173) + MAUI(5057) + Avalonia(5057) 同时运行时，需注意数据库隔离与端口分配。
|