Cyrene/Migration.md

# Cyrene 项目迁移指南：Linux → Windows

## 1. 概述

本文档详细说明如何将 Cyrene 项目从 Linux 开发/运行环境迁移到 Windows 平台。迁移涵盖所有源代码、配置模板、文档和辅助工具，同时排除编译产物、依赖包和敏感信息。

---

## 2. 迁移的文件范围

### ✅ 包含的文件

| 类别 | 路径 | 说明 |
|------|------|------|
| Go 源代码 | `backend/*/cmd/`, `backend/*/internal/` | 所有 Go 后端服务源码 |
| Go 模块文件 | `backend/*/go.mod`, `backend/*/go.sum` | Go 依赖声明 |
| Go workspace | `backend/go.work` | Go 工作区配置 |
| TypeScript/React 源代码 | `frontend/web/src/`, `frontend/packages/` | 前端源码 |
| 前端配置文件 | `frontend/web/vite.config.ts`, `frontend/web/tsconfig.json`, `frontend/web/tailwind.config.ts` 等 | 构建和样式配置 |
| 前端入口 | `frontend/web/index.html` | HTML 入口 |
| 公共资源 | `frontend/web/public/` | 静态资源（头像、背景图、manifest 等） |
| DevTools | `devtools/` | 管理面板源码 |
| Python 测试脚本 | `debug/cache/*.py` | 调试和端到端测试脚本 |
| Shell 调试脚本 | `debug/*.sh`, `debug/*.mjs` | Chromium 调试、诊断脚本 |
| 项目配置 | `.editorconfig`, `.gitignore`, `package.json` 等 | 项目级配置 |
| Docker 配置 | `docker-compose*.yml`, `backend/*/Dockerfile` | 容器化部署配置 |
| Caddy 配置 | `Caddyfile` | 反向代理配置 |
| 文档 | `docs/`, `Deploy.md`, `Migration.md` | 项目文档 |
| 环境变量模板 | `backend/.env.example` | 配置参考模板 |
| 脚本 | `scripts/` | 辅助脚本（migrate.sh, setup-whisper.sh 等） |
| 许可证 | `LICENSE` | 项目许可证 |

### ❌ 排除的文件

| 类别 | 路径模式 | 原因 |
|------|----------|------|
| 编译后的 Go 二进制 | `main`, `backend/*/main`, `backend/*/cmd/*` (不含 `.go`) | 平台相关，需在 Windows 重新编译 |
| Windows 可执行文件 | `*.exe` | 旧的 Windows 编译产物 |
| Node.js 依赖 | `node_modules/`, `frontend/web/node_modules/`, `frontend/node_modules/`, `devtools/node_modules/` | 体积大，通过 `npm install` 重新安装 |
| 前端构建产物 | `frontend/web/dist/` | 通过 `npm run build` 重新构建 |
| 敏感配置文件 | `backend/.env` | 包含 API 密钥和密码 |
| 锁文件 | `package-lock.json`, `frontend/web/package-lock.json`, `frontend/package-lock.json` | 跨平台 npm 依赖树可能不同 |
| Git 内部数据 | `.git/objects`, `.git/refs`, `.git/logs` | 减小压缩包体积 |
| 日志文件 | `*.log`, `logs/`, `debug/logs/` | 运行时产物 |
| 临时文件 | `tmp/` | 临时目录 |

---

## 3. 方式一：Git 克隆（推荐）

Git 是最可靠的跨平台传输方式，保留完整的版本历史和 `.git` 元数据。

```bash
git clone <仓库地址>
cd Cyrene
git checkout dev
```

克隆完成后，手动创建 `backend/.env` 文件：

```bash
# 在 Windows 命令行 (cmd) 中:
copy backend\.env.example backend\.env

# 或在 PowerShell 中:
Copy-Item backend\.env.example backend\.env
```

然后编辑 [`backend/.env`](backend/.env)，填入实际的 API 密钥、数据库密码等配置值。

---

## 4. 方式二：rsync / SCP 传输

使用 [`scripts/migrate.sh`](scripts/migrate.sh) 脚本在 Linux 端打包源文件，排除二进制和编译产物。

```bash
# 打包到默认目录 /tmp
bash scripts/migrate.sh

# 或指定输出目录
bash scripts/migrate.sh ~/Desktop
```

脚本会生成 `cyrene-source-YYYYMMDD_HHMMSS.tar.gz` 压缩包。

然后通过以下任一方式传输到 Windows：

- **U 盘 / 移动硬盘**：直接复制压缩包
- **网络共享 (SMB)**：将压缩包放入共享文件夹，在 Windows 上访问
- **scp**（如果 Windows 启用了 SSH Server）：
  ```bash
  scp /tmp/cyrene-source-*.tar.gz user@windows-host:C:\Users\user\Downloads\
  ```

在 Windows 上解压（需要安装 tar 或使用 7-Zip / WinRAR）：

```bash
# Git Bash / WSL2:
tar -xzf cyrene-source-*.tar.gz

# PowerShell (Windows 10 1803+):
tar -xzf cyrene-source-*.tar.gz
```

---

## 5. Windows 环境准备

### 5.1 基础软件

| 软件 | 最低版本 | 下载地址 | 说明 |
|------|---------|---------|------|
| Go | 1.21+ | https://go.dev/dl/ | Go 编译器，安装后需设置 `GOPATH` |
| Node.js | 18+ (推荐 20+) | https://nodejs.org/ | 包含 npm，用于前端构建 |
| Git for Windows | 最新版 | https://git-scm.com/download/win | 提供 Git Bash 终端 |
| PostgreSQL | 15+ | https://www.postgresql.org/download/windows/ | 数据库，需安装 **pgvector** 扩展 |

### 5.2 PostgreSQL + pgvector 扩展

```sql
-- 连接到 cyrene_ai 数据库后执行
CREATE EXTENSION IF NOT EXISTS vector;
```

> **注意**：Windows 上的 pgvector 安装请参考 https://github.com/pgvector/pgvector#windows

### 5.3 推荐：WSL2

如果希望获得与 Linux 一致的开发体验，推荐启用 WSL2 (Windows Subsystem for Linux)：

```powershell
# 在 PowerShell (管理员) 中执行
wsl --install -d Ubuntu-22.04
```

然后在 WSL2 中按 Linux 原生方式编译和运行。前端开发可在 Windows 原生环境进行以获得更好的热更新体验。

### 5.4 环境变量设置

在 Windows 上有三种方式设置环境变量：

**方式 A：使用 `.env` 文件（推荐）**

项目各服务会自动读取 [`backend/.env`](backend/.env.example)，将 `.env.example` 复制为 `.env` 并填入实际值即可。

**方式 B：命令行临时设置 (cmd)**

```cmd
set LLM_API_KEY=sk-xxxxx
set POSTGRES_PASSWORD=your-password
go run ./cmd/main.go
```

**方式 C：命令行临时设置 (PowerShell)**

```powershell
$env:LLM_API_KEY="sk-xxxxx"
$env:POSTGRES_PASSWORD="your-password"
go run ./cmd/main.go
```

> **注意**：Windows 使用 `set` / `$env:` 而非 Linux 的 `export`。

---

## 6. Windows 上的编译和启动步骤

### 6.1 Go 后端编译

在 Windows 上编译 Go 服务会自动生成 `.exe` 后缀的可执行文件。

```powershell
# 编译 memory-service
cd backend\memory-service
go build -o main.exe .\cmd\main.go

# 编译 iot-debug-service
cd backend\iot-debug-service
go build -o main.exe .\cmd\main.go

# 编译 tool-engine
cd backend\tool-engine
go build -o main.exe .\cmd\main.go

# 编译 ai-core
cd backend\ai-core
go build -o main.exe .\cmd\main.go

# 编译 gateway
cd backend\gateway
go build -o main.exe .\cmd\main.go

# 编译 voice-service (可选)
cd backend\voice-service
go build -o main.exe .\cmd\main.go
```

如果使用 Git Bash，可以用 `/` 路径：

```bash
cd backend/ai-core && go build -o main.exe ./cmd/main.go
```

### 6.2 前端构建

```powershell
cd frontend\web
npm install
npm run build
```

开发模式：

```powershell
npm run dev
```

前端开发服务器将运行在 `http://localhost:5173`。

### 6.3 数据库配置

1. 确保 PostgreSQL 服务已启动
2. 创建数据库和用户（参考 [`backend/.env.example`](backend/.env.example) 中的配置）：

```sql
CREATE USER cyrene WITH PASSWORD 'your-password';
CREATE DATABASE cyrene_ai OWNER cyrene;
\c cyrene_ai
CREATE EXTENSION IF NOT EXISTS vector;
```

3. 在 [`backend/.env`](backend/.env.example) 中配置数据库连接信息。

### 6.4 基础设施服务

使用 Docker Desktop for Windows 启动基础设施：

```powershell
docker-compose -f docker-compose.dev.db.yml up -d
```

这将启动 PostgreSQL、Redis、Qdrant、MinIO 和 NATS 服务。

### 6.5 启动顺序

服务启动顺序很重要，请按以下顺序启动：

| 顺序 | 服务 | 默认端口 | 命令 |
|------|------|---------|------|
| 1 | memory-service | — | `cd backend\memory-service && .\main.exe` |
| 2 | iot-debug-service | 8083 | `cd backend\iot-debug-service && .\main.exe` |
| 3 | tool-engine | — | `cd backend\tool-engine && .\main.exe` |
| 4 | ai-core | 8081 | `cd backend\ai-core && .\main.exe` |
| 5 | gateway | 8080 | `cd backend\gateway && .\main.exe` |

> 每个服务需要在独立的终端窗口中启动。

---

## 7. Windows 特殊注意事项

### 7.1 路径分隔符

Windows 使用反斜杠 `\` 作为路径分隔符，而 Linux 使用正斜杠 `/`。

- **Go 代码**中：`filepath.Join()` 和 `os.PathSeparator` 会自动处理跨平台路径
- **前端代码**中：Vite/Webpack 会自动处理路径
- **配置文件**中：使用正斜杠 `/`（Go 在 Windows 上也能识别）
- **命令行**中：cmd 使用 `\`，PowerShell 和 Git Bash 同时支持 `/` 和 `\`

### 7.2 文件权限

Windows 不需要 `chmod` 命令。Go 编译生成 `.exe` 文件后直接可执行，无需设置执行权限。

### 7.3 端口占用检查

**Windows (cmd)：**

```cmd
netstat -ano | findstr :8080
```

**PowerShell：**

```powershell
Get-NetTCPConnection -LocalPort 8080
```

找到占用端口的 PID 后，使用以下命令终止进程：

```cmd
taskkill /PID <PID> /F
```

### 7.4 换行符差异

- Linux 使用 `LF` (`\n`)
- Windows 使用 `CRLF` (`\r\n`)

建议在 Git for Windows 安装时选择 "Checkout as-is, commit Unix-style line endings"，或将 Git 配置为：

```bash
git config --global core.autocrlf input
```

项目的 [`.editorconfig`](.editorconfig) 文件中已配置换行符规则，大多数 IDE 会自动遵循。

### 7.5 Caddy / 反向代理替代方案

Linux 下使用 Caddy 作为反向代理。Windows 上的替代方案：

- **Caddy for Windows**：https://caddyserver.com/download （原生支持 Windows）
- **Nginx for Windows**：http://nginx.org/en/docs/windows.html
- **直接访问**：开发阶段可直接访问各服务的 localhost 端口，无需反向代理

### 7.6 Chromium Headless

[`debug/chromium_debugging.sh`](debug/chromium_debugging.sh) 脚本是为 Linux 环境编写的。在 Windows 上使用 Chromium headless 需要：

1. 安装 Chrome 或 Chromium 浏览器
2. 手动启动 headless 模式：

```cmd
"C:\Program Files\Google\Chrome\Application\chrome.exe" --headless --remote-debugging-port=9222
```

### 7.7 Docker Desktop

Windows 上的 Docker 容器通过 Docker Desktop 运行。注意：

- 需要启用 Hyper-V 或 WSL2 后端
- 卷挂载路径使用 Windows 路径格式
- `docker-compose.dev.db.yml` 中的相对路径在 PowerShell 中可能需要调整

### 7.8 终端选择

推荐使用以下终端之一：

| 终端 | 路径分隔符 | 推荐度 |
|------|-----------|--------|
| **Git Bash** | `/` | ⭐⭐⭐ 最接近 Linux 体验 |
| **PowerShell 7+** | 兼容 `/` 和 `\` | ⭐⭐⭐ 功能最强大 |
| **cmd** | `\` | ⭐ 不推荐 |

### 7.9 换行符注意事项

编译 Go 源码时可能遇到行尾符警告，可忽略。如需消除警告：

```bash
# 在 Git Bash 中转换所有 Go 文件为 LF
find backend -name "*.go" -exec dos2unix {} \;
```

---

## 8. 验证清单

迁移完成后，逐项检查以下内容：

| # | 检查项 | 验证方法 |
|---|--------|---------|
| 1 | ✅ 所有 Go 服务编译通过 | 在每个 `backend/*` 目录执行 `go build -o main.exe ./cmd/main.go` |
| 2 | ✅ 前端构建成功 | `cd frontend\web && npm run build` 无报错 |
| 3 | ✅ 数据库连接正常 | 使用 `psql` 或数据库客户端连接 PostgreSQL |
| 4 | ✅ pgvector 扩展已安装 | `SELECT * FROM pg_extension WHERE extname='vector';` 返回一行 |
| 5 | ✅ memory-service 启动成功 | 无 panic 日志，监听预期端口 |
| 6 | ✅ iot-debug-service 启动成功 | 访问 `http://localhost:8083/health` 返回 200 |
| 7 | ✅ tool-engine 启动成功 | 无 panic 日志 |
| 8 | ✅ ai-core 启动成功 | 访问 `http://localhost:8081/health` 返回 200 |
| 9 | ✅ gateway 启动成功 | 访问 `http://localhost:8080/health` 返回 200 |
| 10 | ✅ 前端开发服务器启动 | 访问 `http://localhost:5173` 显示登录页面 |
| 11 | ✅ WebSocket 连接正常 | 登录后聊天功能正常，能收到 AI 回复 |
| 12 | ✅ IoT 设备控制正常 | 发送 IoT 控制指令，设备响应正确 |
| 13 | ✅ 语音合成 (TTS) 正常 | AI 回复能正常播放语音 |
| 14 | ✅ 语音识别 (ASR) 正常 | 语音输入能被正确识别 |

---

## 9. 常见问题

### Q: `go build` 报 `package ... is not in GOROOT`

A: 确保在 `backend/` 目录下使用 Go workspace。`backend/go.work` 已配置好模块路径，直接在子目录编译即可。

### Q: `npm install` 报 node-gyp 错误

A: 安装 Windows 构建工具：

```powershell
npm install --global windows-build-tools
```

或安装 Visual Studio Build Tools with C++ workload。

### Q: PostgreSQL 无法连接

A: 检查：
1. PostgreSQL 服务是否启动（`services.msc` 中查看）
2. `pg_hba.conf` 是否允许本地连接
3. 防火墙是否阻止了 5432 端口

### Q: 端口被占用

A: 参考 [7.3 端口占用检查](#73-端口占用检查) 找到并终止占用进程。