docs: add Linux to Windows migration guide and packaging script

2026-05-22 12:32:55 +08:00
parent 9e7ada1ec3
commit e83f28d646
2 changed files with 489 additions and 22 deletions
@@ -0,0 +1,405 @@
+# 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-端口占用检查) 找到并终止占用进程。
@@ -1,28 +1,90 @@
-# scripts/migrate.sh —— 服务端迁移脚本
 #!/bin/bash
-set -e
+# ============================================================
+# Cyrene 项目迁移打包脚本
+# 用途: 在 Linux 环境下生成干净的源代码压缩包，
+#       用于迁移到 Windows 平台。
+# 用法: bash scripts/migrate.sh [输出目录]
+# ============================================================

-echo "📦 昔涟 - 服务迁移脚本"
-echo "=============================="
+set -euo pipefail

-# 1. 停止服务
-echo "1/4 停止当前服务..."
-docker compose down
+# 输出目录，默认为 /tmp
+OUTPUT_DIR="${1:-/tmp}"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+ARCHIVE_NAME="cyrene-source-${TIMESTAMP}.tar.gz"
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"

-# 2. 备份数据
-echo "2/4 备份数据目录..."
-tar -czf "cyrene_backup_$(date +%Y%m%d_%H%M%S).tar.gz" backend/data/
+echo "=== Cyrene 源码打包 ==="
+echo "项目根目录: ${PROJECT_ROOT}"
+echo "输出文件:   ${OUTPUT_DIR}/${ARCHIVE_NAME}"
+echo ""

-# 3. 复制到新服务器 (手动步骤提示)
-# echo "3/4 请将以下文件复制到新服务器:"
-# echo "   - 整个项目目录"
-# echo "   - 或至少: docker-compose.yml, backend/data/, .env"
-# echo ""
-# echo "   rsync -avz ./ user@new-server:/opt/cyrene-ai/"
+# 确保输出目录存在
+mkdir -p "${OUTPUT_DIR}"

-# 4. 在新服务器上启动
-# echo "4/4 在新服务器上执行:"
-# echo "   cd /opt/cyrene-ai"
-# echo "   docker compose up -d"
-# echo ""
-# echo "✅ 迁移完成！昔涟的记忆完好无损~♪"
+cd "${PROJECT_ROOT}"
+
+echo "正在打包..."
+
+# 打包源码，排除二进制和编译产物
+# --exclude 规则说明:
+#   *.exe                     - Windows 可执行文件（旧的编译产物）
+#   backend/*/main            - Go 编译生成的 Linux 二进制
+#   backend/*/cmd/* (非.go)   - 各服务的编译产物
+#   node_modules              - Node.js 依赖
+#   dist                      - 前端构建产物
+#   .env                      - 敏感配置文件
+#   *.log / logs/             - 日志文件
+#   tmp/                      - 临时文件
+#   .git/objects/refs/logs    - Git 内部数据（保留 HEAD 和 config）
+#   package-lock.json         - 锁文件（跨平台重新生成）
+#
+tar -czf "${OUTPUT_DIR}/${ARCHIVE_NAME}" \
+    --exclude='*.exe' \
+    --exclude='main' \
+    --exclude='backend/ai-core/main' \
+    --exclude='backend/ai-core/cmd/ai-core' \
+    --exclude='backend/gateway/main' \
+    --exclude='backend/gateway/cmd/main' \
+    --exclude='backend/memory-service/main' \
+    --exclude='backend/memory-service/cmd/memory-service' \
+    --exclude='backend/tool-engine/cmd/tool-engine' \
+    --exclude='backend/iot-debug-service/cmd/iot-debug-service' \
+    --exclude='backend/voice-service/cmd/voice-service' \
+    --exclude='node_modules' \
+    --exclude='frontend/web/node_modules' \
+    --exclude='frontend/web/dist' \
+    --exclude='frontend/node_modules' \
+    --exclude='devtools/node_modules' \
+    --exclude='frontend/packages/*/node_modules' \
+    --exclude='.env' \
+    --exclude='backend/.env' \
+    --exclude='*.log' \
+    --exclude='logs/' \
+    --exclude='debug/logs/' \
+    --exclude='debug/logs/chromium/' \
+    --exclude='tmp/' \
+    --exclude='.git/objects' \
+    --exclude='.git/refs' \
+    --exclude='.git/logs' \
+    --exclude='package-lock.json' \
+    --exclude='frontend/web/package-lock.json' \
+    --exclude='frontend/package-lock.json' \
+    --exclude='frontend/packages/*/package-lock.json' \
+    .
+
+echo ""
+echo "✅ 打包完成!"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "文件: ${OUTPUT_DIR}/${ARCHIVE_NAME}"
+echo "大小: $(du -h "${OUTPUT_DIR}/${ARCHIVE_NAME}" | cut -f1)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "=== 迁移到 Windows 的步骤 ==="
+echo "1. 将 ${ARCHIVE_NAME} 传输到 Windows 机器（U盘 / 网络共享 / scp）"
+echo "2. 在 Windows 上解压: tar -xzf ${ARCHIVE_NAME}"
+echo "3. 阅读 Migration.md 了解完整迁移流程"
+echo "4. 复制 backend/.env.example 为 backend/.env 并填入实际配置"
+echo "5. 编译并启动服务（参考 Migration.md 第 6 章）"
+echo ""
+echo "提示: 压缩包中已包含文档 docs/ 和 Migration.md，解压后即可查看。"