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 元数据。

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

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

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

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

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

---

4. 方式二：rsync / SCP 传输

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

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

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

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

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

• U 盘 / 移动硬盘：直接复制压缩包
• 网络共享 (SMB)：将压缩包放入共享文件夹，在 Windows 上访问
• scp（如果 Windows 启用了 SSH Server）：

  scp /tmp/cyrene-source-*.tar.gz user@windows-host:C:\Users\user\Downloads\
  

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

# 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 扩展

-- 连接到 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 (管理员) 中执行
wsl --install -d Ubuntu-22.04

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

5.4 环境变量设置

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

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

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

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

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

方式 C：命令行临时设置 (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 后缀的可执行文件。

# 编译 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


# 编译 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，可以用 / 路径：

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

6.2 前端构建

cd frontend\web
npm install
npm run build

开发模式：

npm run dev

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

6.3 数据库配置

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

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 中配置数据库连接信息。

6.4 基础设施服务

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

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

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

6.5 启动顺序

推荐使用 DevTools 一键启动（自动编译 + 按序启动 + 健康检查）：

cd devtools
node src\index.js
:: 浏览器打开 http://localhost:9090，点击「一键启动」

或使用启动脚本：

devtools.bat

DevTools 会按以下顺序自动编译并启动所有 6 个服务：

顺序	服务	端口	说明
1	memory-service	8091	记忆 CRUD 与检索
2	iot-debug-service	8083	模拟智能家居设备
3	voice-service	8093	TTS/STT 语音服务
4	ai-core	8081	LLM 推理与编排
5	gateway	8080	API 网关 / JWT / WebSocket
6	frontend	5173	React 开发服务器

每个步骤会自动等待健康检查通过后再启动下一个服务。如果 Go 二进制未编译，DevTools 会自动先编译再启动。

如需手动逐个启动：

# 按顺序执行，每个在独立终端中运行
cd backend\memory-service && go build -o main.exe .\cmd\main.go && .\main.exe
cd backend\tool-engine && go build -o main.exe .\cmd\main.go && .\main.exe
cd backend\iot-debug-service && go build -o main.exe .\cmd\main.go && .\main.exe
cd backend\voice-service && go build -o main.exe .\cmd\main.go && .\main.exe
cd backend\ai-core && go build -o main.exe .\cmd\main.go && .\main.exe
cd backend\gateway && go build -o main.exe .\cmd\main.go && .\main.exe
cd frontend\web && npm install && npm run dev

---

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)：

netstat -ano | findstr :8080

PowerShell：

Get-NetTCPConnection -LocalPort 8080

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

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 配置为：

git config --global core.autocrlf input

项目的 .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 脚本是为 Linux 环境编写的。在 Windows 上使用 Chromium headless 需要：

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

"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 源码时可能遇到行尾符警告，可忽略。如需消除警告：

# 在 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 日志，监听 8091 端口
6	✅ iot-debug-service 启动成功	访问 http://localhost:8083/api/v1/health 返回 200
7	✅ voice-service 启动成功	访问 http://localhost:8093/api/v1/health 返回 200
8	✅ ai-core 启动成功	访问 http://localhost:8081/api/v1/health 返回 200
9	✅ gateway 启动成功	访问 http://localhost:8080/api/v1/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 构建工具：

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 端口占用检查 找到并终止占用进程。