aiagent/docs/另一台电脑部署文档.md

# 天工智能体平台 — 另一台电脑部署文档

> 完整步骤，从零开始部署到一台新的 Windows 电脑。

---

## 一、前提条件

| 组件 | 版本要求 | 下载地址 |
|------|------|------|
| Python | 3.11+ | https://www.python.org/downloads/ |
| Node.js | 18+ | https://nodejs.org/ |
| MySQL | 5.7+ | https://dev.mysql.com/downloads/ |
| Redis | 7+ | https://github.com/microsoftarchive/redis/releases 或 Docker |
| pnpm | 8+ | `npm install -g pnpm` |
| Git | 任意 | https://git-scm.com/ (可选) |

> 安装 Python / Node.js 时确保勾选 "Add to PATH"。

---

## 二、获取项目文件

### 方式 A：直接拷贝（推荐，已包含数据库备份）

将本机 `D:\aaa\aiagent` 整个目录拷贝到目标机 `D:\aaa\aiagent`。

需要拷贝的目录结构：
```
D:\aaa\aiagent\
├── agent_db_backup.sql      # 数据库备份文件（79MB）
├── backend/                 # 后端源码
├── frontend/                # 前端源码
├── scripts/                 # 启动脚本
├── docs/                    # 文档（含本文档）
└── docker-compose.dev.yml   # Docker 开发环境
```

> 不需要拷贝 `backend\venv`、`frontend\node_modules`、`__pycache__` 等（减少拷贝量）。

### 方式 B：Git 克隆

```powershell
git clone http://101.43.95.130:3001/admin/aiagent.git D:\aaa\aiagent
cd D:\aaa\aiagent
git checkout rjb_win_dev
```

> 注意：Git 克隆不包含数据库备份文件，需单独传入 `agent_db_backup.sql`。

---

## 三、导入数据库

### 1. 创建数据库

```powershell
mysql -uroot -p123456 -e "CREATE DATABASE IF NOT EXISTS agent_db DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

> 如果目标机 MySQL root 密码不同，替换 `123456` 为实际密码。

### 2. 导入备份

```powershell
cd D:\aaa\aiagent
mysql -uroot -p123456 agent_db < agent_db_backup.sql
```

等待约 1-2 分钟完成导入。导入后验证：

```powershell
mysql -uroot -p123456 -e "USE agent_db; SHOW TABLES;"
```

应看到 50+ 张表。

---

## 四、安装后端

```powershell
cd D:\aaa\aiagent\backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
venv\Scripts\Activate.ps1

# 安装 Python 依赖
pip install -r requirements.txt

# 数据库迁移（确保与模型同步）
alembic upgrade head
```

### 检查 .env 配置

确认 `backend\.env` 中的数据库连接正确：

```
DATABASE_URL=mysql+pymysql://root:123456@127.0.0.1:3306/agent_db?charset=utf8mb4
```

> 如果目标机 MySQL root 密码不是 `123456`，修改此行。

---

## 五、安装前端

```powershell
cd D:\aaa\aiagent\frontend

# 安装依赖
pnpm install
```

---

## 六、启动服务

### 一键启动（推荐）

```powershell
cd D:\aaa\aiagent
powershell -ExecutionPolicy Bypass -File .\scripts\startup\start_aiagent.ps1
```

脚本会自动启动：Redis → 后端API (8037) → Celery Worker → Celery Beat → 前端 (3001)

### 或手动逐个启动（排查问题时使用）

分别在 5 个 PowerShell 终端中执行：

**终端 1 — Redis**
```powershell
# 如果已有 Redis 服务则跳过
cd D:\aaa\aiagent\backend\redis
.\redis-server.exe --port 6379
```

**终端 2 — 后端 API**
```powershell
cd D:\aaa\aiagent\backend
venv\Scripts\Activate.ps1
uvicorn app.main:app --host 0.0.0.0 --port 8037
```

**终端 3 — Celery Worker**
```powershell
cd D:\aaa\aiagent\backend
venv\Scripts\Activate.ps1
celery -A app.core.celery_app worker --loglevel=info --pool=threads --concurrency=8
```

**终端 4 — Celery Beat**
```powershell
cd D:\aaa\aiagent\backend
venv\Scripts\Activate.ps1
celery -A app.core.celery_app beat --loglevel=info
```

**终端 5 — 前端**
```powershell
cd D:\aaa\aiagent\frontend
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'
pnpm dev --port 3001
```

---

## 七、验证

| 服务 | 地址 |
|------|------|
| 前端界面 | http://localhost:3001 |
| API 文档 | http://localhost:8037/docs |
| 登录账号 | admin / 123456 |

---

## 八、停止服务

```powershell
# 一键停止
powershell -ExecutionPolicy Bypass -File .\scripts\startup\stop_aiagent.ps1

# 或直接关闭各个 PowerShell 窗口
```

---

## 九、常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| 数据库连接失败 | `.env` 中密码不对 | 修改 `DATABASE_URL` 中的密码 |
| 端口 8037 被占用 | 已有程序使用 | 脚本自动切换到 8041，或手动指定 |
| Redis 启动失败 | Redis 未安装 | 安装 Redis Windows 版或用 Docker 跑 |
| celery Worker 卡住 | Windows fork 问题 | 使用 `--pool=threads`（脚本已默认） |
| 前端请求 500 | API 代理端口不一致 | 检查 `AIAGENT_API_PROXY` 指向正确端口 |
| Tesseract 不可用 | 目标机未装 OCR | 可忽略，仅影响图片 OCR 功能 |

---

## 十、使用 Docker 替代本地服务（可选）

如果不想在目标机安装 MySQL 和 Redis，可以用 Docker 运行：

```powershell
# 启动 MySQL + Redis 容器
docker-compose -f docker-compose.dev.yml up -d

# 修改 .env 中的 DATABASE_URL
# DATABASE_URL=mysql+pymysql://root:dev123@127.0.0.1:3306/agent_db_dev?charset=utf8mb4
```

然后导入备份到 Docker MySQL：

```powershell
docker exec -i aiagent-dev-mysql mysql -uroot -pdev123 agent_db_dev < agent_db_backup.sql
```

---

> 最后更新：2026-06-28