feat: virtual company module, team projects, PWA dishes app, and startup scripts overhaul
- Add company module (3-tier org, CEO planning, parallel departments) - Add company orchestrator, knowledge extractor, presets, scheduler - Add company API endpoints, models, and frontend views - Add 今天吃啥 PWA app (69 dishes, real images, offline support) - Add team_projects output directory structure - Add unified manage.ps1 for service lifecycle - Add Windows startup guide v1.0 - Add TTS troubleshooting doc - Update frontend (AgentChat UX overhaul, new views) - Update backend (voice engine fix, multi-tenant, RBAC) - Remove deprecated startup scripts and old docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
213
docs/startup-deploy/(红头)Windows服务器启动与重启唯一指南(1.0版本).md
Normal file
213
docs/startup-deploy/(红头)Windows服务器启动与重启唯一指南(1.0版本).md
Normal file
@@ -0,0 +1,213 @@
|
||||
# (红头)Windows 服务器启动与重启唯一指南（1.0 版本）
|
||||
|
||||
> 替代旧版，后续只看这一份。
|
||||
> 仓库路径：`D:\workspace\aiagent`（若你的路径不同，替换下文所有路径即可）
|
||||
|
||||
---
|
||||
|
||||
## 0. 快速参考卡片
|
||||
|
||||
```powershell
|
||||
cd D:\workspace\aiagent
|
||||
|
||||
# 最常用 — 全套重启
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\manage.ps1 restart
|
||||
|
||||
# 查看服务状态
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\manage.ps1 status
|
||||
|
||||
# 只改后端代码后（保留 Redis + 前端）
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1
|
||||
```
|
||||
|
||||
| 服务 | 端口 | 说明 |
|
||||
|------|------|------|
|
||||
| 前端 Vite | 3001 | `http://localhost:3001` |
|
||||
| 后端 API | 8037（主）/ 8041（备） | `http://127.0.0.1:8037/docs` |
|
||||
| Redis | 6379 | `restart_backend_celery.ps1` 会自动守护 |
|
||||
| Celery Worker | — | Agent 异步执行 |
|
||||
| Celery Beat | — | 定时任务调度 |
|
||||
|
||||
---
|
||||
|
||||
## 1. manage.ps1 — 统一管理（推荐）
|
||||
|
||||
一条命令管理所有服务，替代原来散落的 start/stop/restart。
|
||||
|
||||
```powershell
|
||||
cd D:\workspace\aiagent
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\manage.ps1 <动作>
|
||||
```
|
||||
|
||||
| 动作 | 功能 |
|
||||
|------|------|
|
||||
| `status` | 检查所有服务状态（端口 + 健康检查） |
|
||||
| `start` | 启动全部：Redis → API(自动选端口) → Celery → 前端 |
|
||||
| `stop` | 停止全部服务，显示端口释放情况 |
|
||||
| `restart` | = stop + start，**推荐用于全套重启** |
|
||||
|
||||
### 1.1 start 自动处理
|
||||
|
||||
- **端口探测**：8037 被占用自动切 8041
|
||||
- **Redis 守护**：不在运行则自动拉起
|
||||
- **前端代理对齐**：自动设置 `AIAGENT_API_PROXY` 指向实际 API 端口
|
||||
- **健康检查**：启动后等待最多 30s，确认 API `/docs` 和前端端口可达
|
||||
|
||||
### 1.2 输出示例
|
||||
|
||||
```
|
||||
== 启动所有服务 ==
|
||||
>>> 1/5 Redis
|
||||
[OK] Redis 已启动 (端口 6379)
|
||||
>>> 2/5 后端 API 端口探测
|
||||
[OK] 端口 8037 可用
|
||||
>>> 3/5 后端 API (端口 8037)
|
||||
[OK] 后端 API 已启动 (PID=12345)
|
||||
>>> 4/5 Celery Worker + Beat
|
||||
[OK] Celery Worker 已在新窗口启动 (PID=12346)
|
||||
[OK] Celery Beat 已在新窗口启动 (PID=12347)
|
||||
>>> 5/5 前端 Vite (端口 3001)
|
||||
[OK] 前端 Vite 已启动 (PID=12348)
|
||||
|
||||
>>> 健康检查（等待服务就绪，最多 30 秒）
|
||||
[OK] 所有服务就绪（耗时 12s）
|
||||
|
||||
═══════════════════════════════════════════
|
||||
启动完成
|
||||
═══════════════════════════════════════════
|
||||
后端文档: http://127.0.0.1:8037/docs
|
||||
前端页面: http://localhost:3001
|
||||
Agent对话: http://localhost:3001/agent-chat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. restart_backend_celery.ps1 — 仅重启后端（保留 Redis + 前端）
|
||||
|
||||
适用场景：只改了 Python 代码、.env、依赖、工具实现。
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1
|
||||
```
|
||||
|
||||
**关键改进（1.0 新增）：**
|
||||
- 重启 API + Celery 后**自动检查 Redis 是否在运行**
|
||||
- Redis 不在则自动拉起（不再出现"重启后登录报 500"）
|
||||
- 不会主动停止 Redis 或前端
|
||||
|
||||
---
|
||||
|
||||
## 3. 手动应急启动（manage.ps1 不可用时）
|
||||
|
||||
开 3~5 个终端：
|
||||
|
||||
**1) Redis**
|
||||
```powershell
|
||||
D:\workspace\aiagent\backend\redis\redis-server.exe --port 6379
|
||||
```
|
||||
|
||||
**2) API**
|
||||
```powershell
|
||||
cd D:\workspace\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8037
|
||||
```
|
||||
|
||||
**3) Celery Worker**
|
||||
```powershell
|
||||
cd D:\workspace\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m celery -A app.core.celery_app worker --loglevel=info --pool=threads --concurrency=8
|
||||
```
|
||||
|
||||
**4) 前端**
|
||||
```powershell
|
||||
cd D:\workspace\aiagent\frontend
|
||||
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'
|
||||
npx vite --port 3001 --host 0.0.0.0
|
||||
```
|
||||
|
||||
**5) Celery Beat（定时任务，可选）**
|
||||
```powershell
|
||||
cd D:\workspace\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m celery -A app.core.celery_app beat --loglevel=info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 常见故障速查
|
||||
|
||||
### 4.1 登录报 500 / "服务器内部错误"
|
||||
|
||||
**根因：Redis 未运行。**
|
||||
`restart_backend_celery.ps1` 旧版只重启 API+Celery，不检查 Redis。1.0 版已修复。
|
||||
|
||||
**手动修复：**
|
||||
```powershell
|
||||
D:\workspace\aiagent\backend\redis\redis-server.exe --port 6379
|
||||
```
|
||||
|
||||
### 4.2 TTS 朗读声音机械不自然
|
||||
|
||||
**根因：** 后端 edge-tts CLI 子进程找不到，降级到浏览器机械语音。
|
||||
|
||||
**日志特征：**
|
||||
```
|
||||
ERROR | Edge TTS 失败:
|
||||
POST /api/v1/voice/tts - 状态码: 502
|
||||
```
|
||||
|
||||
**已修复：** `voice.py` 改用 Python 库直接调用，不再依赖外部 CLI PATH。
|
||||
|
||||
详细排查见 `docs/troubleshooting/TTS朗读声音机械不自然.md`。
|
||||
|
||||
### 4.3 端口 8037 被僵尸进程占用
|
||||
|
||||
**现象：** `netstat` 显示 8037 LISTENING，但 `tasklist` 找不到对应 PID。
|
||||
|
||||
**解决：**
|
||||
- `manage.ps1 start` 会自动探测并切换到 8041
|
||||
- 必须清理 8037：重启 Windows，或 `netsh interface ipv4 show excludedportrange protocol=tcp` 检查是否与 Hyper-V 动态端口冲突
|
||||
|
||||
### 4.4 Agent 执行超时 `timeout of 30000ms exceeded`
|
||||
|
||||
**优先检查：**
|
||||
1. Redis 是否在 6379 监听：`netstat -ano | findstr :6379`
|
||||
2. `.env` 中 `REDIS_URL` 是否与 Redis 实际端口一致（应为 `redis://localhost:6379/0`）
|
||||
3. Celery Worker 是否在运行
|
||||
|
||||
### 4.5 一键脚本报 PowerShell 解析错误
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -Scope Process Bypass
|
||||
```
|
||||
或将脚本保存为 UTF-8 with BOM 重新执行。
|
||||
|
||||
---
|
||||
|
||||
## 5. 端口说明
|
||||
|
||||
| 服务 | 主端口 | 备用端口 | 启动方式 |
|
||||
|------|--------|----------|----------|
|
||||
| 前端 Vite | 3001 | — | manage.ps1 / 手动 |
|
||||
| 后端 API | 8037 | 8041 | manage.ps1 自动探测 |
|
||||
| Redis | 6379 | — | manage.ps1 自动守护 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 访问地址
|
||||
|
||||
- 前端：`http://localhost:3001`
|
||||
- Agent 对话：`http://localhost:3001/agent-chat`
|
||||
- 后端文档：`http://127.0.0.1:8037/docs`（若切到 8041 则改端口）
|
||||
- 健康检查：`curl.exe -s -o NUL -w "%{http_code}" http://127.0.0.1:8037/docs`（返回 200 即正常）
|
||||
|
||||
---
|
||||
|
||||
## 7. 维护规则（强制）
|
||||
|
||||
- 所有启动/重启内容只维护本文件
|
||||
- 建议用 `manage.ps1` 替代旧脚本进行全套操作
|
||||
- `restart_backend_celery.ps1` 仅用于"只改后端代码"的场景
|
||||
- 修改启动逻辑后，先更新本文档
|
||||
@@ -1,245 +0,0 @@
|
||||
# (红头)Windows 服务器启动与重启唯一指南
|
||||
|
||||
本文是 `D:\aaa\aiagent` 在 Windows 本地开发环境下的**唯一启动/重启文档**。
|
||||
后续只看这一份即可。
|
||||
|
||||
---
|
||||
|
||||
## 0. 统一结论（先看）
|
||||
|
||||
- 推荐端口：
|
||||
- 前端：`3001`
|
||||
- 后端 API：`8037`（若被占用，一键启动会自动改用备用 **`8041`**）
|
||||
- Redis：`6379`
|
||||
- **一键脚本目录**：均在仓库内 `scripts\startup\`，在根目录 `D:\aaa\aiagent` 下执行时路径为 `.\scripts\startup\*.ps1`（勿写成根目录下的 `.\start_aiagent.ps1`）。
|
||||
- `backend/.env` 必须与实际 Redis 端口一致：
|
||||
- 推荐：`REDIS_URL=redis://localhost:6379/0`
|
||||
- 任何 `.env` / 依赖 / 工具代码变更后，至少重启：
|
||||
- API + Celery（`scripts\startup\restart_backend_celery.ps1`）
|
||||
- 若出现 `timeout of 30000ms exceeded`，优先检查：
|
||||
1) Redis 是否可连
|
||||
2) Celery Worker 是否在跑
|
||||
3) API 与 Worker 是否使用同一 `backend\venv`
|
||||
|
||||
---
|
||||
|
||||
## 1. 一键启动 / 停止 / 重启
|
||||
|
||||
在 PowerShell 中执行（仓库根目录）：
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent
|
||||
```
|
||||
|
||||
### 1.1 一键启动（全套）
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\start_aiagent.ps1
|
||||
```
|
||||
|
||||
默认目标：
|
||||
- 前端：`http://localhost:3001`
|
||||
- 后端文档：优先 `http://127.0.0.1:8037/docs`；若脚本提示已切到 **8041**，则打开 `http://127.0.0.1:8041/docs`
|
||||
- Redis：`127.0.0.1:6379`
|
||||
|
||||
一键启动会为每个进程新开 PowerShell 窗口（含 **Celery Worker** 与 **Celery Beat**）。若控制台一闪退出，请到该窗口里看报错。
|
||||
|
||||
### 1.2 一键停止（全套）
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\stop_aiagent.ps1
|
||||
```
|
||||
|
||||
### 1.3 仅重启后端 + Celery（最常用）
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1
|
||||
```
|
||||
|
||||
适用场景：改了 `.env`、Python 依赖、内置工具实现、Agent 执行逻辑。
|
||||
|
||||
说明：该脚本**固定**把 API 起在 **8037**。若本机 8037 被其它程序或异常状态占用，请先 `stop` 全套或释放端口后再执行。
|
||||
|
||||
### 1.4 仅重启前端（不动 Redis / 后端）
|
||||
|
||||
适用：只改了前端代码或 Vite 配置，需要刷新 dev 进程。
|
||||
|
||||
1. 结束占用 **3001** 的进程（任务管理器结束对应 `node`/`pnpm`，或用资源监视器按端口查 PID 后结束）。
|
||||
2. 确认当前 API 端口（一般为 **8037**；若全套启动时曾提示改用 **8041**，则与之一致）。
|
||||
3. 新开 PowerShell：
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\frontend
|
||||
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037' # 若 API 在 8041，改为 ...8041
|
||||
pnpm dev --port 3001
|
||||
```
|
||||
|
||||
浏览器请优先用 **`http://localhost:3001`** 访问（Vite 常只绑 `[::1]`，用 `127.0.0.1:3001` 可能连不上，属正常现象）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 标准“重启服务器”流程（推荐照抄）
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\stop_aiagent.ps1
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\startup\start_aiagent.ps1
|
||||
```
|
||||
|
||||
若 `start` 输出中出现 **`Port 8037 is occupied, switching to 8041`**，则本次 API 在 **8041**，下文健康检查与文档地址请改用 **8041**（前端新窗口里的 `AIAGENT_API_PROXY` 已指向该端口）。
|
||||
|
||||
完成后立刻验证（PowerShell 中 `curl` 多为 `Invoke-WebRequest` 别名，建议用 **`curl.exe`**）：
|
||||
|
||||
```powershell
|
||||
netstat -ano | findstr :6379
|
||||
netstat -ano | findstr :8037
|
||||
netstat -ano | findstr :8041
|
||||
netstat -ano | findstr :3001
|
||||
curl.exe -s -o NUL -w "%{http_code}" http://127.0.0.1:8037/health
|
||||
curl.exe -s -o NUL -w "%{http_code}" http://127.0.0.1:8041/health
|
||||
```
|
||||
|
||||
若 API 实际在 **8041**，刚启动后 **10～20 秒内** `/health` 可能仍超时，属 uvicorn 拉起过程；前端 `3001` 可先就绪。
|
||||
|
||||
---
|
||||
|
||||
## 3. 本次故障复盘（学生作业管理助手超时）
|
||||
|
||||
### 3.1 现象
|
||||
|
||||
- Agent 对话区报错：`发送失败: timeout of 30000ms exceeded`
|
||||
- 前端可打开，但执行一直超时。
|
||||
|
||||
### 3.2 根因
|
||||
|
||||
1. `backend/.env` 配置为：
|
||||
- `REDIS_URL=redis://localhost:6380/0`
|
||||
2. 实际 Redis 监听在：
|
||||
- `6379`
|
||||
3. 导致 Celery 任务队列链路异常（或 Worker 无法稳定消费），Agent 执行超时。
|
||||
|
||||
### 3.3 修复
|
||||
|
||||
1. 将 `backend/.env` 改为：
|
||||
- `REDIS_URL=redis://localhost:6379/0`
|
||||
2. 执行：
|
||||
- `powershell -ExecutionPolicy Bypass -File .\scripts\startup\restart_backend_celery.ps1`
|
||||
3. 验证：
|
||||
- `6379/8037/3001` 监听正常
|
||||
- `/health` 返回 `200`
|
||||
- Celery worker 进程存在
|
||||
|
||||
### 3.4 预防
|
||||
|
||||
- 不要混用两套端口约定（`6379` 与 `6380`）。
|
||||
- 每次重启后先做 1 分钟健康检查（端口 + `/health` + 1 条 Agent 测试消息）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 常见问题与快速处理
|
||||
|
||||
### 4.1 执行策略拦截脚本
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -Scope Process Bypass
|
||||
```
|
||||
|
||||
### 4.2 `start_aiagent.ps1` 报 PowerShell 解析错误
|
||||
|
||||
症状：出现 `ParserError`、字符串终止符缺失、`[OK]` 附近报错。
|
||||
|
||||
处理：
|
||||
1. 临时手动启动（见 4.3）
|
||||
2. 将脚本保存为 **UTF-8（建议无 BOM）/ ASCII 兼容内容**，避免中文引号或异常字符
|
||||
|
||||
### 4.3 一键脚本不可用时的手动拉起（应急）
|
||||
|
||||
开 **5** 个终端（与一键启动对齐；若暂不需要定时任务可省略 Beat）：
|
||||
|
||||
1) Redis
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\backend\redis
|
||||
.\redis-server.exe --port 6379
|
||||
```
|
||||
|
||||
2) API
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8037
|
||||
```
|
||||
|
||||
3) Celery
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m celery -A app.core.celery_app worker --loglevel=info --pool=threads --concurrency=8
|
||||
```
|
||||
|
||||
4) 前端
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\frontend
|
||||
$env:AIAGENT_API_PROXY='http://127.0.0.1:8037'
|
||||
pnpm dev --port 3001
|
||||
```
|
||||
|
||||
5) Celery Beat（与一键 `start_aiagent.ps1` 对齐；定时任务依赖此项）
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\backend
|
||||
.\venv\Scripts\Activate.ps1
|
||||
python -m celery -A app.core.celery_app beat --loglevel=info
|
||||
```
|
||||
|
||||
### 4.4 8037「占用」与 netstat 幽灵 PID（实践经验）
|
||||
|
||||
部分 Windows 环境会出现：
|
||||
|
||||
- `start_aiagent.ps1` 提示 **8037 被占用**，自动改用 **8041**；
|
||||
- `netstat` 仍显示 `0.0.0.0:8037 LISTENING` 且带某一 **PID**，但 **`tasklist` 查不到该 PID**（或无法 `Stop-Process`）。
|
||||
|
||||
此时以 **`start` 脚本打印的实际端口为准**（多为 **8041**），用 **`http://127.0.0.1:8041/docs`** 与对应 `/health` 验证即可。若必须清理 **8037**，可本机执行 `netsh interface ipv4 show excludedportrange protocol=tcp` 查看是否与 Hyper-V / 动态端口保留冲突，或重启 Windows 后再全套启动。
|
||||
|
||||
### 4.5 `stop` 已正常但 `start` 报「8037 与 8041 均占用」
|
||||
|
||||
曾出现：`stop` 对后端端口打印 **SKIP**，端口检查却仍显示 **LISTEN**，随后 `start` 抛出双端口占用。根因是旧版 `stop_aiagent.ps1` 中 **`ForEach-Object` 内误用 `return`**（会从整个函数提前返回）以及内层 **`$pid` 变量名与 PowerShell 只读自动变量冲突**，导致未真正枚举监听 PID。
|
||||
|
||||
**当前仓库内 `scripts\startup\stop_aiagent.ps1` 已按上述问题修复**；若你本地脚本被回退或拷贝了旧版，请与仓库版本对齐后再执行全套重启。
|
||||
|
||||
---
|
||||
|
||||
## 5. OCR（上传图片识别）必查项
|
||||
|
||||
`backend/.env` 建议：
|
||||
|
||||
```ini
|
||||
TESSERACT_CMD=C:/Program Files/Tesseract-OCR/tesseract.exe
|
||||
TESSERACT_TESSDATA_DIR=D:/aaa/aiagent/tessdata
|
||||
```
|
||||
|
||||
自检：
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent\backend
|
||||
.\venv\Scripts\python scripts\check_ocr_env.py
|
||||
```
|
||||
|
||||
若新增依赖后仍报 OCR 缺失，重启 Celery。
|
||||
|
||||
---
|
||||
|
||||
## 6. 访问地址
|
||||
|
||||
- 前端：`http://localhost:3001`（推荐用 **localhost**，避免与 `[::1]` 绑定不一致）
|
||||
- 后端 API（默认）：`http://127.0.0.1:8037`
|
||||
- 后端文档（默认）：`http://127.0.0.1:8037/docs`
|
||||
- 健康检查（默认）：`http://127.0.0.1:8037/health`
|
||||
- 若一键启动提示改用 **8041**：将上述三项中的端口改为 **8041** 即可。
|
||||
|
||||
---
|
||||
|
||||
## 7. 维护规则（强制）
|
||||
|
||||
- 所有 Windows 启动/重启内容只维护本文件。
|
||||
- 其他旧文档仅保留跳转，不再写重复步骤。
|
||||
- 修改启动逻辑后，先更新本文件再通知团队。
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
# 前后端服务器启动和停止（已合并）
|
||||
|
||||
本文件已停止维护。
|
||||
请改看唯一文档：`(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
路径：`D:\aaa\aiagent\(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
# 启动注意事项（已合并）
|
||||
|
||||
本文件已停止维护。
|
||||
请改看唯一文档：`(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
路径：`D:\aaa\aiagent\(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
@@ -1,474 +0,0 @@
|
||||
# Windows 启动指南（已合并）
|
||||
|
||||
本文件已停止维护，请只看以下唯一文档：
|
||||
|
||||
- `D:\aaa\aiagent\(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
说明：历史内容已合并至上方文档，后续不再在本文件更新。
|
||||
|
||||
# Windows 启动指南（已合并）
|
||||
|
||||
本文件已停止维护。
|
||||
请改看唯一文档：`(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
路径：`D:\aaa\aiagent\(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
# Windows 本地启动指南
|
||||
|
||||
## 前置要求
|
||||
|
||||
### 已安装的软件
|
||||
- ✅ Python 3.12.7（已安装）
|
||||
- ✅ Node.js 22.13.0（已安装）
|
||||
- ✅ npm 10.9.2（已安装）
|
||||
- ✅ pnpm 10.33.0（已安装）
|
||||
|
||||
### 需要安装的软件
|
||||
- ❌ Redis（需要安装，但可以选择便携版）
|
||||
|
||||
## 步骤 1：安装 Redis（选择一种方式）
|
||||
|
||||
### 选项 A：使用 Docker 运行 Redis（推荐，最简单）
|
||||
|
||||
如果你不介意使用 Docker 来运行 Redis（其他服务仍在本地运行）：
|
||||
|
||||
1. **安装 Docker Desktop**
|
||||
- 下载地址：https://www.docker.com/products/docker-desktop/
|
||||
- 安装后启动 Docker Desktop
|
||||
|
||||
2. **启动 Redis 容器**
|
||||
```bash
|
||||
docker run -d --name redis -p 6380:6379 redis:7-alpine
|
||||
```
|
||||
|
||||
3. **验证 Redis 是否运行**
|
||||
```bash
|
||||
docker ps
|
||||
```
|
||||
应该能看到 Redis 容器正在运行。
|
||||
|
||||
### 选项 B：使用 Redis 便携版（快速启动，无需安装）
|
||||
|
||||
1. **下载 Redis Windows 便携版**
|
||||
```bash
|
||||
cd "D:/aaa/aiagent/backend"
|
||||
curl -L -o redis.zip "https://github.com/microsoftarchive/redis/releases/download/win-3.2.100/Redis-x64-3.2.100.zip"
|
||||
```
|
||||
|
||||
2. **解压 Redis**
|
||||
```bash
|
||||
# Windows PowerShell
|
||||
Expand-Archive -Path redis.zip -DestinationPath redis
|
||||
# 或使用解压工具解压
|
||||
```
|
||||
|
||||
3. **启动 Redis 服务器**
|
||||
```bash
|
||||
cd redis
|
||||
./redis-server.exe redis.windows.conf
|
||||
```
|
||||
Redis 将在端口 6379 启动。
|
||||
|
||||
4. **验证 Redis 是否运行**
|
||||
```bash
|
||||
./redis-cli.exe ping
|
||||
```
|
||||
应该返回：`PONG`
|
||||
|
||||
### 选项 C：安装 Redis for Windows（作为服务）
|
||||
|
||||
1. **下载 Redis Windows 版本**
|
||||
- 从 GitHub 下载：https://github.com/microsoftarchive/redis/releases
|
||||
- 下载 `Redis-x64-3.2.100.msi`
|
||||
|
||||
2. **安装 Redis**
|
||||
- 运行安装程序，按照默认设置安装
|
||||
- 安装完成后，Redis 会作为 Windows 服务运行
|
||||
|
||||
3. **修改 Redis 端口（可选）**
|
||||
- 默认 Redis 运行在 6379 端口
|
||||
- 如果需要使用 6380 端口（与 docker-compose 配置一致），需要修改配置文件
|
||||
- 配置文件位置：`C:\Program Files\Redis\redis.windows-service.conf`
|
||||
- 找到 `port 6379` 改为 `port 6380`
|
||||
- 重启 Redis 服务
|
||||
|
||||
### 选项 D：使用 WSL 安装 Redis
|
||||
|
||||
如果你有 WSL（Windows Subsystem for Linux）：
|
||||
|
||||
```bash
|
||||
# 在 WSL 中运行
|
||||
sudo apt update
|
||||
sudo apt install redis-server
|
||||
sudo service redis-server start
|
||||
# 需要配置 Redis 允许远程连接
|
||||
```
|
||||
|
||||
## 步骤 2：配置后端环境
|
||||
|
||||
### 1. 创建虚拟环境并安装依赖
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# 创建虚拟环境
|
||||
python -m venv venv
|
||||
|
||||
# 激活虚拟环境
|
||||
# Windows CMD:
|
||||
venv\Scripts\activate
|
||||
# Windows PowerShell:
|
||||
.\venv\Scripts\Activate.ps1
|
||||
# Git Bash:
|
||||
source venv/Scripts/activate
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 配置环境变量
|
||||
|
||||
```bash
|
||||
# 复制环境变量文件
|
||||
copy env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env` 文件，确保以下配置正确：
|
||||
|
||||
```ini
|
||||
# 数据库配置（已配置为腾讯云MySQL，无需修改）
|
||||
DATABASE_URL=mysql+pymysql://root:!Rjb12191@gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com:24936/agent_db?charset=utf8mb4
|
||||
|
||||
# Redis配置（根据你的Redis安装方式选择）
|
||||
# 如果使用Docker Redis（端口6380）：
|
||||
REDIS_URL=redis://localhost:6380/0
|
||||
# 如果使用Windows Redis（默认端口6379）：
|
||||
# REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# CORS配置
|
||||
CORS_ORIGINS=http://localhost:3001,http://127.0.0.1:3001,http://localhost:3000,http://127.0.0.1:3000,http://localhost:8038,http://101.43.95.130:8038
|
||||
|
||||
# DeepSeek API密钥（已有）
|
||||
DEEPSEEK_API_KEY=sk-fdf7cc1c73504e628ec0119b7e11b8cc
|
||||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||||
```
|
||||
|
||||
### 3. 运行数据库迁移
|
||||
|
||||
```bash
|
||||
# 确保虚拟环境已激活
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### 4. 启动后端服务
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8037 --reload
|
||||
```
|
||||
|
||||
后端服务将在 http://localhost:8037 启动。
|
||||
|
||||
### 5. 启动 Celery Worker（新终端）
|
||||
|
||||
```bash
|
||||
# 在新终端中，进入backend目录并激活虚拟环境
|
||||
cd backend
|
||||
venv\Scripts\activate
|
||||
|
||||
# 启动 Celery Worker
|
||||
celery -A app.core.celery_app worker --loglevel=info
|
||||
```
|
||||
|
||||
## 步骤 3：配置前端环境
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 2. 配置 API 地址
|
||||
|
||||
编辑 `frontend/vite.config.ts`，确保代理配置正确：
|
||||
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
server: {
|
||||
port: 3001,
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8037',
|
||||
changeOrigin: true,
|
||||
},
|
||||
'/ws': {
|
||||
target: 'ws://localhost:8037',
|
||||
ws: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### 3. 启动前端服务
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
前端服务将在 http://localhost:3001 启动。
|
||||
注意：访问地址是 http://localhost:3001，前端默认使用3001端口。
|
||||
|
||||
## 步骤 4：验证服务
|
||||
|
||||
### 1. 检查服务状态
|
||||
|
||||
- **后端API**: http://localhost:8037
|
||||
- **API文档**: http://localhost:8037/docs
|
||||
- **前端**: http://localhost:3001
|
||||
|
||||
### 2. 测试健康检查
|
||||
|
||||
```bash
|
||||
curl http://localhost:8037/health
|
||||
```
|
||||
应该返回：`{"status":"healthy"}`
|
||||
|
||||
## 步骤 5：创建第一个工作流
|
||||
|
||||
1. 访问 http://localhost:3001
|
||||
2. 注册新用户或使用现有账户登录
|
||||
3. 点击"创建工作流"进入可视化编辑器
|
||||
4. 拖拽节点、连接、配置并保存
|
||||
5. 运行工作流测试
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. Redis 连接失败
|
||||
|
||||
**错误信息**：
|
||||
```
|
||||
redis.exceptions.ConnectionError: Error 10061 connecting to localhost:6380
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
- 检查 Redis 是否正在运行
|
||||
- 确认 Redis 端口是否正确
|
||||
- 检查防火墙是否阻止了 Redis 端口
|
||||
|
||||
### 2. 数据库连接失败
|
||||
|
||||
**错误信息**：
|
||||
```
|
||||
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...")
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
- 检查网络连接（腾讯云数据库需要互联网访问）
|
||||
- 确认数据库连接信息正确
|
||||
- 检查数据库是否允许远程连接
|
||||
|
||||
### 3. 前端无法连接后端
|
||||
|
||||
**错误信息**：
|
||||
```
|
||||
Proxy error: Could not proxy request /api/auth/me from localhost:3001 to http://localhost:8037
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
- 检查后端服务是否正在运行（http://localhost:8037）
|
||||
- 检查前端代理配置（vite.config.ts）
|
||||
- 检查 CORS 配置（.env 文件中的 CORS_ORIGINS）
|
||||
|
||||
### 4. Celery 任务不执行
|
||||
|
||||
**解决方案**：
|
||||
- 检查 Celery Worker 是否正在运行
|
||||
- 检查 Redis 连接是否正常
|
||||
- 查看 Celery Worker 日志
|
||||
|
||||
### 5. 端口被占用
|
||||
|
||||
**解决方案**：
|
||||
- 检查端口 8037 和 3001 是否被其他程序占用
|
||||
- 可以修改端口：
|
||||
- 后端：修改启动命令端口 `--port 8038`
|
||||
- 前端：修改 `vite.config.ts` 中的 `port`
|
||||
|
||||
## 一键启动脚本（推荐）
|
||||
|
||||
下面给出一套更稳的 PowerShell 一键启动脚本：
|
||||
- 自动检查并启动 Redis（优先使用 `backend/redis/redis-server.exe`）
|
||||
- 自动拉起后端 API（默认 8037，若被占用自动切到 8041）
|
||||
- 自动拉起 Celery Worker
|
||||
- 自动拉起前端（并将前端代理指向实际 API 端口）
|
||||
|
||||
### 脚本文件：`start_aiagent.ps1`
|
||||
|
||||
> 建议保存到仓库根目录：`D:\aaa\aiagent\start_aiagent.ps1`
|
||||
|
||||
```powershell
|
||||
param(
|
||||
[int]$ApiPort = 8037,
|
||||
[int]$FallbackApiPort = 8041,
|
||||
[int]$FrontendPort = 3001
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
$RepoRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$Backend = Join-Path $RepoRoot "backend"
|
||||
$Frontend = Join-Path $RepoRoot "frontend"
|
||||
$RedisDir = Join-Path $Backend "redis"
|
||||
$RedisExe = Join-Path $RedisDir "redis-server.exe"
|
||||
$RedisCli = Join-Path $RedisDir "redis-cli.exe"
|
||||
|
||||
function Test-PortListening([int]$Port) {
|
||||
$line = netstat -ano | Select-String ":$Port\s+.*LISTENING" | Select-Object -First 1
|
||||
return [bool]$line
|
||||
}
|
||||
|
||||
function Ensure-Redis {
|
||||
if (Test-PortListening 6379) {
|
||||
Write-Host "[OK] Redis already listening on 6379" -ForegroundColor Green
|
||||
return
|
||||
}
|
||||
if (-not (Test-Path $RedisExe)) {
|
||||
throw "Redis 可执行文件不存在：$RedisExe"
|
||||
}
|
||||
Write-Host "[RUN] Starting Redis on 6379 ..." -ForegroundColor Yellow
|
||||
Start-Process -FilePath $RedisExe -ArgumentList "--port 6379" -WorkingDirectory $RedisDir | Out-Null
|
||||
Start-Sleep -Seconds 2
|
||||
if (-not (Test-PortListening 6379)) {
|
||||
throw "Redis 启动失败，6379 未监听"
|
||||
}
|
||||
if (Test-Path $RedisCli) {
|
||||
& $RedisCli -p 6379 ping | Out-Null
|
||||
}
|
||||
Write-Host "[OK] Redis started" -ForegroundColor Green
|
||||
}
|
||||
|
||||
function Resolve-ApiPort {
|
||||
if (-not (Test-PortListening $ApiPort)) {
|
||||
return $ApiPort
|
||||
}
|
||||
Write-Host "[WARN] Port $ApiPort is occupied, switching to $FallbackApiPort" -ForegroundColor Yellow
|
||||
if (Test-PortListening $FallbackApiPort) {
|
||||
throw "端口 $ApiPort 和 $FallbackApiPort 都被占用，请先释放端口"
|
||||
}
|
||||
return $FallbackApiPort
|
||||
}
|
||||
|
||||
Write-Host "== AIAgent Windows 一键启动 ==" -ForegroundColor Cyan
|
||||
Write-Host "Repo: $RepoRoot"
|
||||
|
||||
Ensure-Redis
|
||||
$RealApiPort = Resolve-ApiPort
|
||||
$ApiBase = "http://127.0.0.1:$RealApiPort"
|
||||
|
||||
Write-Host "[RUN] Starting backend API on $RealApiPort ..." -ForegroundColor Yellow
|
||||
Start-Process powershell -ArgumentList @(
|
||||
"-NoExit",
|
||||
"-Command",
|
||||
"cd '$Backend'; .\venv\Scripts\Activate.ps1; python -m uvicorn app.main:app --host 0.0.0.0 --port $RealApiPort"
|
||||
)
|
||||
|
||||
Write-Host "[RUN] Starting Celery worker ..." -ForegroundColor Yellow
|
||||
Start-Process powershell -ArgumentList @(
|
||||
"-NoExit",
|
||||
"-Command",
|
||||
"cd '$Backend'; .\venv\Scripts\Activate.ps1; python -m celery -A app.core.celery_app worker --loglevel=info --pool=threads --concurrency=8"
|
||||
)
|
||||
|
||||
Write-Host "[RUN] Starting frontend on $FrontendPort (proxy -> $ApiBase) ..." -ForegroundColor Yellow
|
||||
Start-Process powershell -ArgumentList @(
|
||||
"-NoExit",
|
||||
"-Command",
|
||||
"`$env:AIAGENT_API_PROXY='$ApiBase'; cd '$Frontend'; pnpm dev --port $FrontendPort"
|
||||
)
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "[DONE] 启动命令已下发" -ForegroundColor Green
|
||||
Write-Host "前端: http://localhost:$FrontendPort" -ForegroundColor Cyan
|
||||
Write-Host "后端: $ApiBase/docs" -ForegroundColor Cyan
|
||||
Write-Host "Redis: 127.0.0.1:6379" -ForegroundColor Cyan
|
||||
```
|
||||
|
||||
### 运行方式
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent
|
||||
powershell -ExecutionPolicy Bypass -File .\start_aiagent.ps1
|
||||
```
|
||||
|
||||
### 可选参数
|
||||
|
||||
```powershell
|
||||
# 指定端口
|
||||
powershell -ExecutionPolicy Bypass -File .\start_aiagent.ps1 -ApiPort 8037 -FallbackApiPort 8041 -FrontendPort 3001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速启动脚本（简版）
|
||||
|
||||
### Windows CMD 脚本 (`start_all.cmd`)
|
||||
|
||||
```batch
|
||||
@echo off
|
||||
echo 启动天工智能体平台...
|
||||
|
||||
REM 启动后端服务
|
||||
start cmd /k "cd /d backend && venv\Scripts\activate && uvicorn app.main:app --host 0.0.0.0 --port 8037 --reload"
|
||||
|
||||
REM 启动 Celery Worker
|
||||
start cmd /k "cd /d backend && venv\Scripts\activate && celery -A app.core.celery_app worker --loglevel=info"
|
||||
|
||||
REM 启动前端服务
|
||||
start cmd /k "cd /d frontend && pnpm dev"
|
||||
|
||||
echo 服务启动完成！
|
||||
echo 前端: http://localhost:3001
|
||||
echo 后端API: http://localhost:8037/docs
|
||||
```
|
||||
|
||||
### PowerShell 脚本 (`start_all.ps1`)
|
||||
|
||||
```powershell
|
||||
Write-Host "启动天工智能体平台..." -ForegroundColor Green
|
||||
|
||||
# 启动后端服务
|
||||
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd backend; .\venv\Scripts\Activate.ps1; uvicorn app.main:app --host 0.0.0.0 --port 8037 --reload"
|
||||
|
||||
# 启动 Celery Worker
|
||||
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd backend; .\venv\Scripts\Activate.ps1; celery -A app.core.celery_app worker --loglevel=info"
|
||||
|
||||
# 启动前端服务
|
||||
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd frontend; pnpm dev"
|
||||
|
||||
Write-Host "服务启动完成！" -ForegroundColor Green
|
||||
Write-Host "前端: http://localhost:3001" -ForegroundColor Yellow
|
||||
Write-Host "后端API: http://localhost:8037/docs" -ForegroundColor Yellow
|
||||
```
|
||||
|
||||
## 停止服务
|
||||
|
||||
### 停止所有服务
|
||||
1. 按 `Ctrl+C` 停止每个终端中的服务
|
||||
2. 停止 Redis：
|
||||
- Docker Redis: `docker stop redis`
|
||||
- Windows Redis 服务: 停止 "Redis" 服务
|
||||
|
||||
## 生产环境建议
|
||||
|
||||
对于生产环境，建议使用：
|
||||
1. **Docker Compose**：统一管理和部署所有服务
|
||||
2. **Nginx**：反向代理和负载均衡
|
||||
3. **Supervisor**：进程管理
|
||||
4. **数据库备份**：定期备份腾讯云数据库
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 1.1
|
||||
**最后更新**: 2026-04-09
|
||||
|
||||
> 注意：本指南针对 Windows 本地开发环境。生产环境部署请参考 [方案-优化版.md](./方案-优化版.md)。
|
||||
@@ -1,100 +0,0 @@
|
||||
# Windows 启动和停止用法（已合并）
|
||||
|
||||
本文件已停止维护，请只看以下唯一文档：
|
||||
|
||||
- `D:\aaa\aiagent\(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
说明：历史内容已合并至上方文档，后续不再在本文件更新。
|
||||
|
||||
# Windows 启动和停止用法（已合并）
|
||||
|
||||
本文件已停止维护。
|
||||
请改看唯一文档：`(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
路径：`D:\aaa\aiagent\(红头)Windows服务器启动与重启唯一指南.md`
|
||||
|
||||
# AIAgent Windows 启动和停止用法
|
||||
|
||||
## 一键启动
|
||||
|
||||
在 PowerShell 中执行：
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent
|
||||
powershell -ExecutionPolicy Bypass -File .\start_aiagent.ps1
|
||||
```
|
||||
|
||||
启动后默认访问：
|
||||
- 前端：`http://localhost:3001`
|
||||
- 后端文档：`http://127.0.0.1:8037/docs`
|
||||
- Redis：`127.0.0.1:6379`
|
||||
|
||||
说明：
|
||||
- 若 `8037` 被占用，脚本会自动切换到 `8041` 启动后端。
|
||||
- 前端会自动使用 `AIAGENT_API_PROXY` 指向实际后端端口。
|
||||
|
||||
## 启动参数（可选）
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\start_aiagent.ps1 -ApiPort 8037 -FallbackApiPort 8041 -FrontendPort 3001
|
||||
```
|
||||
|
||||
## 一键停止
|
||||
|
||||
在 PowerShell 中执行：
|
||||
|
||||
```powershell
|
||||
cd D:\aaa\aiagent
|
||||
powershell -ExecutionPolicy Bypass -File .\stop_aiagent.ps1
|
||||
```
|
||||
|
||||
会尝试停止以下进程：
|
||||
- 后端 API（`uvicorn app.main:app`）
|
||||
- Celery Worker（`celery -A app.core.celery_app worker`）
|
||||
- 前端 dev（`vite` / `pnpm dev` / `npm run dev`）
|
||||
- Redis（`redis-server`）
|
||||
|
||||
并检查端口：
|
||||
- `3001`
|
||||
- `8037`
|
||||
- `8041`
|
||||
- `6379`
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1) 执行策略拦截脚本
|
||||
|
||||
先执行：
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -Scope Process Bypass
|
||||
```
|
||||
|
||||
### 2) 发送消息超时（30 秒）
|
||||
|
||||
优先检查 Redis 和 Worker：
|
||||
|
||||
```powershell
|
||||
netstat -ano | findstr :6379
|
||||
```
|
||||
|
||||
确认 Celery Worker 正在运行。
|
||||
|
||||
### 3) 8037 端口被占用
|
||||
|
||||
先查占用：
|
||||
|
||||
```powershell
|
||||
netstat -ano | findstr :8037
|
||||
```
|
||||
|
||||
再结束对应 PID（管理员 PowerShell）：
|
||||
|
||||
```powershell
|
||||
taskkill /PID <PID> /T /F
|
||||
```
|
||||
|
||||
## 脚本文件位置
|
||||
|
||||
- 启动脚本：`D:\aaa\aiagent\start_aiagent.ps1`
|
||||
- 停止脚本：`D:\aaa\aiagent\stop_aiagent.ps1`
|
||||
@@ -1,104 +0,0 @@
|
||||
# 🚀 启动说明
|
||||
|
||||
## 使用 Docker Compose 启动（推荐）
|
||||
|
||||
### 1. 启动所有服务
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
```
|
||||
|
||||
### 2. 查看服务状态
|
||||
|
||||
```bash
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
### 3. 查看日志
|
||||
|
||||
```bash
|
||||
# 查看所有服务日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 查看特定服务日志
|
||||
docker-compose logs -f backend
|
||||
docker-compose logs -f frontend
|
||||
docker-compose logs -f celery
|
||||
```
|
||||
|
||||
### 4. 停止服务
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 5. 重启服务
|
||||
|
||||
```bash
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
## 📍 访问地址
|
||||
|
||||
- **前端**: http://localhost:8038
|
||||
- **后端API**: http://localhost:8037
|
||||
- **API文档**: http://localhost:8037/docs
|
||||
- **健康检查**: http://localhost:8037/health
|
||||
|
||||
## 🔧 配置说明
|
||||
|
||||
### 数据库配置
|
||||
|
||||
- **数据库类型**: MySQL（腾讯云数据库）
|
||||
- **连接地址**: gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com:24936
|
||||
- **数据库名**: agent_db
|
||||
- **字符集**: utf8mb4
|
||||
|
||||
### 端口配置
|
||||
|
||||
- **前端端口**: 8038（容器内3000）
|
||||
- **后端端口**: 8037（容器内8000）
|
||||
- **Redis端口**: 6379
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **数据库连接**: 确保服务器能够访问腾讯云MySQL数据库
|
||||
2. **首次启动**: 首次启动可能需要一些时间下载镜像和安装依赖
|
||||
3. **数据库迁移**: 首次运行需要执行数据库迁移（如果需要）
|
||||
4. **环境变量**: 数据库连接信息已在docker-compose.dev.yml中配置
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### 1. 容器启动失败
|
||||
|
||||
检查：
|
||||
- Docker 和 Docker Compose 是否正常运行
|
||||
- 端口是否被占用（8038, 8037, 6379）
|
||||
- 磁盘空间是否充足
|
||||
|
||||
### 2. 数据库连接失败
|
||||
|
||||
检查：
|
||||
- 网络是否能够访问腾讯云数据库
|
||||
- 数据库连接信息是否正确
|
||||
- 数据库是否已创建
|
||||
|
||||
### 3. 前端无法访问后端
|
||||
|
||||
检查：
|
||||
- 后端服务是否正常运行
|
||||
- 前端配置的API URL是否正确
|
||||
- CORS配置是否正确
|
||||
|
||||
### 4. Celery任务不执行
|
||||
|
||||
检查：
|
||||
- Celery Worker容器是否正常运行
|
||||
- Redis连接是否正常
|
||||
- 查看Celery日志：`docker-compose logs -f celery`
|
||||
|
||||
## 📝 下一步
|
||||
|
||||
1. 访问 http://localhost:8037/docs 查看API文档
|
||||
2. 开始开发功能模块
|
||||
3. 参考 [方案-优化版.md](./方案-优化版.md) 了解详细技术方案
|
||||
79
docs/troubleshooting/TTS朗读声音机械不自然.md
Normal file
79
docs/troubleshooting/TTS朗读声音机械不自然.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# TTS 朗读声音机械/不自然 — 排查与修复
|
||||
|
||||
## 现象
|
||||
|
||||
AgentChat 页面点击朗读，声音机械不自然，不像微软神经网络语音。
|
||||
|
||||
## 根因
|
||||
|
||||
有两种可能，依序排查：
|
||||
|
||||
### 1. edge-tts 子进程找不到（最常见）
|
||||
|
||||
`voice.py` 中 `_edge_tts_synthesize` 原本通过 `subprocess` 调用 `edge-tts` CLI，但服务器若在新 PowerShell 窗口启动，PATH 可能不包含 venv/Scripts，导致调用失败。后端返回 502，前端 `useTTS.ts` 静默降级到浏览器 `SpeechSynthesis`（声音机械）。
|
||||
|
||||
**日志特征：**
|
||||
```
|
||||
ERROR | Edge TTS 失败:
|
||||
POST /api/v1/voice/tts - 状态码: 502
|
||||
```
|
||||
|
||||
**修复：** 已改用 edge-tts Python 库直接调用，不再依赖 CLI 子进程。
|
||||
|
||||
```python
|
||||
# voice.py — _edge_tts_synthesize()
|
||||
import edge_tts
|
||||
communicate = edge_tts.Communicate(text, voice, rate=rate_str)
|
||||
await communicate.save(output_path)
|
||||
```
|
||||
|
||||
### 2. Redis 未运行
|
||||
|
||||
登录接口依赖 Redis 存储 refresh_token。Redis 挂掉时登录报 500，但更隐蔽的是 TTS 接口需要认证，Redis 超时会导致请求堆积。
|
||||
|
||||
**日志特征：**
|
||||
```
|
||||
Redis连接失败: Timeout connecting to server
|
||||
redis.exceptions.TimeoutError: Timeout connecting to server
|
||||
```
|
||||
|
||||
**修复：** 确保 Redis 在 6379 端口运行：
|
||||
```bash
|
||||
/d/workspace/aiagent/backend/redis/redis-server.exe --port 6379
|
||||
```
|
||||
|
||||
> 注意：`restart_backend_celery.ps1` 只重启 API+Celery，不重启 Redis 和前端。全停后再启请用 `start_aiagent.ps1` 或手动启动 Redis。
|
||||
|
||||
## 验证方法
|
||||
|
||||
```bash
|
||||
# 1. 确认后端 TTS 正常
|
||||
TOKEN=$(curl -s -X POST http://127.0.0.1:8041/api/v1/auth/login \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-d "username=admin&password=123456" | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
|
||||
|
||||
curl -s -X POST http://127.0.0.1:8041/api/v1/voice/tts \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text":"你好测试","voice":"xiaoxiao","speed":1.0}'
|
||||
|
||||
# 应返回: {"audio_url":"/api/v1/voice/audio/xxx.mp3",...}
|
||||
|
||||
# 2. 确认音频文件可下载
|
||||
curl -s -o /dev/null -w "HTTP: %{http_code}" http://127.0.0.1:8041/api/v1/voice/audio/xxx.mp3
|
||||
# 应返回: HTTP: 200
|
||||
```
|
||||
|
||||
## 端口说明
|
||||
|
||||
| 服务 | 主端口 | 备用端口 | 说明 |
|
||||
|------|--------|----------|------|
|
||||
| 后端 API | 8037 | 8041 | 8037 被僵尸进程占用时换 8041 |
|
||||
| 前端 Vite | 3001 | — | `AIAGENT_API_PROXY` 需指向实际后端端口 |
|
||||
| Redis | 6379 | — | `restart_backend_celery.ps1` 不会启动它 |
|
||||
|
||||
## 为什么不能加微软情感 SSML
|
||||
|
||||
`<mstts:express-as>` 是 Azure 认知服务付费功能，免费的 Edge TTS（edge-tts 库底层使用的微软 Edge 浏览器朗读接口）**不支持**该标签。强行注入 SSML 会直接导致 `NoAudioReceived` 错误。
|
||||
|
||||
`zh-CN-XiaoxiaoNeural` 本身已是神经网络语音，不加 express-as 也能正常发音。若需更强情感表现力，只能接入 Azure Speech Services（需付费订阅和 API Key）。
|
||||
@@ -1,104 +0,0 @@
|
||||
# 产品经理
|
||||
|
||||
> 所属公司：瑞来兹软件技术有限公司
|
||||
> 更新日期：2026-05-04
|
||||
|
||||
---
|
||||
|
||||
## 一、角色定义
|
||||
|
||||
产品经理（Product Manager）是产品的所有者，负责从需求发现到产品上线的全生命周期管理，在用户价值与商业价值之间寻找最优解。
|
||||
|
||||
---
|
||||
|
||||
## 二、主要职责
|
||||
|
||||
### 2.1 需求管理
|
||||
- 收集并分析用户反馈、业务需求、市场趋势
|
||||
- 撰写 BRD（商业需求文档）和 PRD（产品需求文档）
|
||||
- 维护产品 Backlog，持续进行需求优先级排序
|
||||
- 组织需求评审会，协同技术、设计、测试对齐需求
|
||||
|
||||
### 2.2 产品规划
|
||||
- 制定产品路线图（Roadmap），明确版本迭代节奏
|
||||
- 定义产品核心指标（KPI/OKR），跟踪产品数据表现
|
||||
- 竞品分析与市场调研，输出竞品分析报告
|
||||
- 参与公司战略规划，对齐产品方向与业务目标
|
||||
|
||||
### 2.3 功能设计
|
||||
- 输出产品原型（低保真/高保真）、交互流程图
|
||||
- 编写用户故事（User Story）和验收标准（AC）
|
||||
- 与 UX/UI 设计师协作完成界面设计
|
||||
- 定义功能边界、异常状态、权限模型
|
||||
|
||||
### 2.4 项目推进
|
||||
- 参与 Sprint Planning、每日站会、Sprint Review
|
||||
- 在开发过程中澄清需求细节，及时调整方案
|
||||
- 组织 UAT（用户验收测试），确认上线条件
|
||||
- 版本发布后撰写 Release Notes，组织功能宣讲
|
||||
|
||||
### 2.5 数据分析与迭代
|
||||
- 上线后跟踪产品数据（DAU、留存率、转化率等）
|
||||
- 通过 A/B 测试验证功能假设
|
||||
- 收集用户反馈，驱动下一轮产品迭代
|
||||
- 定期输出产品月报/季报
|
||||
|
||||
---
|
||||
|
||||
## 三、常用平台与工具
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **原型设计** | Axure RP | 高保真原型、复杂交互 |
|
||||
| | Figma | UI 协作设计、原型演示 |
|
||||
| | 墨刀（Mockplus） | 快速原型、团队协作 |
|
||||
| | Sketch | Mac 端 UI 设计 |
|
||||
| **项目管理** | Jira | 需求跟踪、Sprint 管理 |
|
||||
| | 禅道 | 国产项目管理、Bug 跟踪 |
|
||||
| | Trello | 轻量看板管理 |
|
||||
| | Notion | 文档协作、知识库 |
|
||||
| | Confluence | 需求文档 Wiki |
|
||||
| | PingCode | 国产研发管理平台 |
|
||||
| **文档协作** | 飞书文档 | 内部协作与文档 |
|
||||
| | 语雀 | 知识库与文档 |
|
||||
| | 石墨文档 | 在线协同编辑 |
|
||||
| | Google Docs | 国际团队协作 |
|
||||
| **数据分析** | 神策数据 | 用户行为分析 |
|
||||
| | GrowingIO | 无埋点数据分析 |
|
||||
| | Google Analytics | Web 流量分析 |
|
||||
| | 友盟+ | 移动端数据统计 |
|
||||
| | Metabase / Superset | BI 自助分析 |
|
||||
| **沟通协作** | 飞书 / 钉钉 / 企业微信 | 即时通讯 |
|
||||
| | Slack | 国际团队通讯 |
|
||||
| | Zoom / 腾讯会议 | 视频会议 |
|
||||
| **思维导图** | XMind | 需求梳理、功能拆解 |
|
||||
| | ProcessOn | 流程图、脑图在线 |
|
||||
| | Draw.io | 架构图、流程图 |
|
||||
|
||||
---
|
||||
|
||||
## 四、能力模型
|
||||
|
||||
| 能力 | 要求 |
|
||||
|------|------|
|
||||
| 需求洞察 | 能从模糊业务诉求中提炼可执行需求 |
|
||||
| 逻辑思维 | 严谨的功能边界与异常流梳理 |
|
||||
| 数据分析 | SQL 查询、指标体系搭建、A/B 实验设计 |
|
||||
| 沟通协调 | 跨部门（技术/设计/运营/销售）高效沟通 |
|
||||
| 技术理解 | 了解前后端基础、API 概念、数据库基础 |
|
||||
| 商业思维 | 理解商业模式、ROI 评估、定价策略 |
|
||||
|
||||
---
|
||||
|
||||
## 五、产出物清单
|
||||
|
||||
| 产出物 | 交付节点 |
|
||||
|--------|----------|
|
||||
| 竞品分析报告 | 产品立项前 |
|
||||
| BRD（商业需求文档） | 立项阶段 |
|
||||
| PRD（产品需求文档） | 需求评审前 |
|
||||
| 产品原型 | 需求评审前 |
|
||||
| 用户故事地图 | Sprint 规划前 |
|
||||
| 产品路线图 | 季度/年度规划 |
|
||||
| 产品数据月报 | 每月 |
|
||||
| Release Notes | 每个版本发布 |
|
||||
@@ -1,153 +0,0 @@
|
||||
# 开发
|
||||
|
||||
> 所属公司：瑞来兹软件技术有限公司
|
||||
> 更新日期：2026-05-04
|
||||
|
||||
---
|
||||
|
||||
## 一、角色定义
|
||||
|
||||
开发工程师（Developer）是产品的建造者，负责将需求和设计转化为可运行的软件系统，涵盖前端、后端、移动端、数据等多个方向。
|
||||
|
||||
---
|
||||
|
||||
## 二、主要职责
|
||||
|
||||
### 2.1 编码实现
|
||||
- 根据 PRD 和技术方案完成功能开发
|
||||
- 编写高质量、可维护、可测试的代码
|
||||
- 遵循编码规范和团队约定的设计模式
|
||||
- 实现 API 接口、数据库操作、业务逻辑
|
||||
- 前端页面还原、交互实现、状态管理
|
||||
|
||||
### 2.2 代码质量
|
||||
- 编写单元测试（Jest/JUnit/pytest），保证核心逻辑覆盖率
|
||||
- 代码自测，确保提测质量
|
||||
- 参与 Code Review，互相审查代码质量
|
||||
- 使用 SonarQube / ESLint 等工具确保代码规范
|
||||
- 重构遗留代码，消除技术债务
|
||||
|
||||
### 2.3 技术方案
|
||||
- 参与技术方案评审，评估实现可行性
|
||||
- 编写模块级别的详细设计文档
|
||||
- 评估需求实现工时（Story Point / 人天）
|
||||
- 对复杂功能进行技术预研（Spike）
|
||||
|
||||
### 2.4 协作与交付
|
||||
- 参与 Sprint 规划、每日站会、评审会
|
||||
- 与测试工程师协作定位和修复 Bug
|
||||
- 与产品经理澄清需求实现细节
|
||||
- 配合运维完成服务上线、灰度发布
|
||||
- 编写上线 Checklist 和技术 Release Notes
|
||||
|
||||
### 2.5 学习与成长
|
||||
- 持续学习新技术、新框架
|
||||
- 参与技术分享，沉淀团队知识
|
||||
- 阅读优秀开源项目源码
|
||||
- 初级工程师接受高级/架构师指导
|
||||
|
||||
---
|
||||
|
||||
## 三、常用平台与工具
|
||||
|
||||
### 3.1 后端开发
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **语言与框架** | Go + Gin / Kratos | 微服务开发 |
|
||||
| | Java + Spring Boot / Spring Cloud | 企业级后端 |
|
||||
| | Python + FastAPI / Django | 快速开发 / AI 服务 |
|
||||
| | Node.js + Nest.js / Express | BFF 层 / 轻量服务 |
|
||||
| | Rust | 高性能系统 |
|
||||
| **数据库** | MySQL / PostgreSQL | 关系型数据 |
|
||||
| | Redis | 缓存、队列、锁 |
|
||||
| | MongoDB | 文档存储 |
|
||||
| | Elasticsearch | 全文搜索 |
|
||||
| **消息队列** | Kafka / RocketMQ / RabbitMQ | 异步解耦 |
|
||||
| **IDE** | VS Code / IntelliJ IDEA / GoLand | 开发环境 |
|
||||
| **API 工具** | Postman / Apifox / Apipost | 接口调试 |
|
||||
| | Swagger / OpenAPI | API 文档 |
|
||||
|
||||
### 3.2 前端开发
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **框架** | React + Next.js | Web 前端 |
|
||||
| | Vue 3 + Nuxt | Web 前端 |
|
||||
| | TypeScript | 类型安全 |
|
||||
| **UI 库** | Ant Design / Element Plus | 中后台组件 |
|
||||
| | Tailwind CSS | 原子化 CSS |
|
||||
| | Shadcn/ui | 可定制组件 |
|
||||
| **构建工具** | Vite / Webpack / Turbopack | 构建打包 |
|
||||
| **状态管理** | Zustand / Pinia / Redux | 状态管理 |
|
||||
| **测试** | Vitest / Playwright / Cypress | 单元/端到端测试 |
|
||||
| **IDE** | VS Code / Cursor | 开发环境 |
|
||||
| **调试** | Chrome DevTools / React DevTools | 调试工具 |
|
||||
|
||||
### 3.3 移动端开发
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **平台** | Swift + SwiftUI（iOS） | iOS 原生 |
|
||||
| | Kotlin + Jetpack Compose（Android） | Android 原生 |
|
||||
| | Flutter / React Native | 跨端开发 |
|
||||
| **测试** | XCTest（iOS）/ Espresso（Android） | 单元/UI 测试 |
|
||||
| **分发** | TestFlight / Firebase App Distribution | 测试分发 |
|
||||
| **性能** | Instruments（iOS）/ Android Profiler | 性能分析 |
|
||||
|
||||
### 3.4 通用工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| Git + GitHub / GitLab / Gitee | 版本控制 |
|
||||
| Docker | 容器化开发环境 |
|
||||
| VS Code / JetBrains 系列 | IDE |
|
||||
| Tmux / iTerm2 / Windows Terminal | 终端 |
|
||||
| Figma（查看模式） | 设计稿查看 |
|
||||
| Raycast / Alfred | 效率工具 |
|
||||
|
||||
---
|
||||
|
||||
## 四、开发流程
|
||||
|
||||
```
|
||||
需求理解 → 技术方案 → 编码实现 → 自测 → 代码评审 → 提测 → 修复Bug → 上线
|
||||
│ │ │ │ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
|
||||
PRD阅读 设计文档 分支开发 单元测试 PR/MR 提测单 Bug修复 发布清单
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、能力模型
|
||||
|
||||
| 级别 | 能力要求 |
|
||||
|------|----------|
|
||||
| **初级** | 独立完成明确需求的功能开发、Bug 修复 |
|
||||
| **中级** | 独立负责模块设计与实现、指导初级工程师 |
|
||||
| **高级** | 主导子系统设计、跨模块优化、Code Review 把控 |
|
||||
| **资深** | 领域专家、技术难题攻关、架构设计参与 |
|
||||
|
||||
| 通用能力 | 要求 |
|
||||
|----------|------|
|
||||
| 编程语言 | 精通至少一门语言及其生态 |
|
||||
| 数据结构与算法 | 常见数据结构、算法复杂度分析 |
|
||||
| 设计模式 | 常用 23 种模式，能合理应用 |
|
||||
| 数据库 | SQL 编写、索引优化、慢查询分析 |
|
||||
| Linux | 命令行操作、脚本编写、服务部署 |
|
||||
| Git | 分支管理、冲突解决、Git Flow |
|
||||
| 调试能力 | 日志分析、断点调试、性能 Profiling |
|
||||
|
||||
---
|
||||
|
||||
## 六、产出物清单
|
||||
|
||||
| 产出物 | 交付节点 |
|
||||
|--------|----------|
|
||||
| 技术方案/详细设计 | 编码前 |
|
||||
| 功能代码（含单测） | Sprint 结束 |
|
||||
| API 接口文档更新 | 接口变更时 |
|
||||
| 自测报告 | 提测时 |
|
||||
| Code Review 记录 | 每个 PR/MR |
|
||||
| 上线 Checklist | 发布前 |
|
||||
| 技术分享文档 | 不定期 |
|
||||
@@ -1,130 +0,0 @@
|
||||
# 架构师
|
||||
|
||||
> 所属公司：瑞来兹软件技术有限公司
|
||||
> 更新日期：2026-05-04
|
||||
|
||||
---
|
||||
|
||||
## 一、角色定义
|
||||
|
||||
架构师（Architect）是技术方向的掌舵者，负责系统架构设计、技术选型、非功能需求保障（性能/安全/可扩展性），并在关键决策上提供技术判断力。按领域可细分为：系统架构师、应用架构师、数据架构师、安全架构师、解决方案架构师。
|
||||
|
||||
---
|
||||
|
||||
## 二、主要职责
|
||||
|
||||
### 2.1 架构设计
|
||||
- 设计系统整体架构（微服务/单体/混合），产出架构图
|
||||
- 定义模块边界、服务拆分、接口契约（API 设计）
|
||||
- 制定技术选型标准（语言、框架、中间件、数据库）
|
||||
- 设计数据架构：数据模型、分库分表策略、读写分离
|
||||
- 设计部署架构：K8s 集群规划、网络拓扑、容灾方案
|
||||
|
||||
### 2.2 技术规范
|
||||
- 制定编码规范、分支管理策略（Git Flow / Trunk-Based）
|
||||
- 定义 API 设计规范（RESTful / GraphQL / gRPC）
|
||||
- 建立技术雷达（Tech Radar），跟踪新兴技术
|
||||
- 制定安全编码规范（OWASP Top 10 防护）
|
||||
- 编写架构决策记录（ADR）
|
||||
|
||||
### 2.3 非功能需求保障
|
||||
- 性能优化：系统吞吐量、响应时间、并发能力
|
||||
- 高可用设计：多活/主备、故障转移、降级熔断
|
||||
- 安全架构：认证授权（OAuth2.0/OIDC）、数据加密、审计日志
|
||||
- 可扩展性：水平扩展策略、CQRS、事件驱动
|
||||
- 可观测性：日志、指标、链路追踪（OpenTelemetry）
|
||||
|
||||
### 2.4 技术评审与治理
|
||||
- 主持技术方案评审会，评估方案可行性
|
||||
- 核心模块代码审查，确保架构一致性
|
||||
- 识别技术债务，制定偿还计划
|
||||
- 参与技术委员会，制定长期技术战略
|
||||
|
||||
### 2.5 团队赋能
|
||||
- 指导高级开发工程师，提升团队技术水位
|
||||
- 定期组织技术分享会（Tech Talk）
|
||||
- 编写架构文档，降低系统认知负荷
|
||||
- 帮助团队攻克技术难题（攻关）
|
||||
|
||||
---
|
||||
|
||||
## 三、常用平台与工具
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **架构设计** | Draw.io | 架构图、流程图、网络拓扑 |
|
||||
| | PlantUML | 代码生成 UML 图 |
|
||||
| | C4 Model / Structurizr | 分层架构可视化 |
|
||||
| | Excalidraw | 手绘风格架构草图 |
|
||||
| | ArchiMate | 企业架构建模 |
|
||||
| **技术文档** | Confluence / Notion | 架构文档协作 |
|
||||
| | ADR Tools | 架构决策记录管理 |
|
||||
| | Markdown + Git | 轻量文档版本管理 |
|
||||
| **中间件与基础设施** | Kubernetes (K8s) | 容器编排 |
|
||||
| | Istio / Linkerd | 服务网格 |
|
||||
| | Nacos / Consul | 服务注册与配置 |
|
||||
| | Redis | 缓存 / 分布式锁 |
|
||||
| | Kafka / RocketMQ / RabbitMQ | 消息队列 |
|
||||
| | Nginx / APISIX / Kong | API 网关 |
|
||||
| | Elasticsearch | 搜索与分析引擎 |
|
||||
| **数据库** | MySQL / PostgreSQL | 关系型数据库 |
|
||||
| | MongoDB | 文档型 NoSQL |
|
||||
| | TiDB / CockroachDB | 分布式 SQL |
|
||||
| | ClickHouse / Doris | OLAP 分析 |
|
||||
| **监控与可观测** | Prometheus + Grafana | 监控与可视化 |
|
||||
| | ELK（Elasticsearch + Logstash + Kibana） | 日志管理 |
|
||||
| | SkyWalking / Jaeger / Zipkin | 链路追踪 |
|
||||
| | Sentry | 错误追踪 |
|
||||
| **CI/CD** | Jenkins / GitLab CI / GitHub Actions | 流水线 |
|
||||
| | ArgoCD | GitOps 部署 |
|
||||
| | Docker / Containerd | 容器化 |
|
||||
| **安全** | SonarQube | 代码安全扫描 |
|
||||
| | Vault | 密钥管理 |
|
||||
| | OWASP ZAP | 安全测试 |
|
||||
|
||||
---
|
||||
|
||||
## 四、架构设计原则
|
||||
|
||||
```
|
||||
1. KISS（Keep It Simple, Stupid）—— 简单优于复杂
|
||||
2. YAGNI（You Aren't Gonna Need It）—— 不为未来过度设计
|
||||
3. 高内聚低耦合 —— 模块内紧密关联，模块间松散依赖
|
||||
4. 关注点分离（Separation of Concerns）
|
||||
5. 面向失败设计（Design for Failure）
|
||||
6. 无状态优先 —— 有状态服务需特殊设计
|
||||
7. 数据一致性权衡 —— CAP 取舍、最终一致性
|
||||
8. API First —— 先定义接口，再实现
|
||||
9. 12-Factor App —— 云原生应用方法论
|
||||
10. 安全左移（Shift Left on Security）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、能力模型
|
||||
|
||||
| 能力 | 要求 |
|
||||
|------|------|
|
||||
| 系统设计 | 分布式系统、微服务、领域驱动设计（DDD） |
|
||||
| 技术广度 | 多语言/多框架/多数据库经验 |
|
||||
| 抽象思维 | 从业务需求抽象架构模型 |
|
||||
| 决策能力 | 技术选型与权衡（Trade-off）分析 |
|
||||
| 沟通表达 | 能用图/文档清晰传达架构意图 |
|
||||
| 业务理解 | 理解业务战略，支撑业务扩展 |
|
||||
| 领导力 | 技术驱动，不依赖职级 |
|
||||
|
||||
---
|
||||
|
||||
## 六、产出物清单
|
||||
|
||||
| 产出物 | 交付节点 |
|
||||
|--------|----------|
|
||||
| 系统架构设计文档 | 项目启动阶段 |
|
||||
| 技术选型报告 | 方案评审 |
|
||||
| API 设计规范 | 编码前 |
|
||||
| 数据库 ER 图与表设计 | 编码前 |
|
||||
| 部署架构图 | 上线前 |
|
||||
| 架构评审记录 | 每次评审 |
|
||||
| ADR（架构决策记录） | 关键决策时 |
|
||||
| 性能压测报告 | 上线前 |
|
||||
| 技术雷达 | 季度 |
|
||||
@@ -1,162 +0,0 @@
|
||||
# 测试
|
||||
|
||||
> 所属公司：瑞来兹软件技术有限公司
|
||||
> 更新日期：2026-05-04
|
||||
|
||||
---
|
||||
|
||||
## 一、角色定义
|
||||
|
||||
测试工程师（QA Engineer）是产品质量的守门员，通过功能测试、自动化测试、性能测试、安全测试等手段，保障软件交付质量，降低线上故障风险。
|
||||
|
||||
---
|
||||
|
||||
## 二、主要职责
|
||||
|
||||
### 2.1 测试规划
|
||||
- 参与需求评审，从测试角度提出可测性建议
|
||||
- 编写测试计划，明确测试范围、策略、资源
|
||||
- 设计测试用例（功能、异常、边界、兼容性）
|
||||
- 评估测试工作量，规划测试排期
|
||||
- 定义测试准入/准出标准
|
||||
|
||||
### 2.2 功能测试
|
||||
- 执行冒烟测试（Smoke Test），验证提测版本可用性
|
||||
- 执行全量测试用例，记录测试结果
|
||||
- 发现 Bug 并提交到缺陷管理平台，清晰描述复现步骤
|
||||
- 回归测试：验证 Bug 修复，确保无新增问题
|
||||
- 探索性测试：发现用例未覆盖的缺陷
|
||||
|
||||
### 2.3 自动化测试
|
||||
- 搭建自动化测试框架（Selenium / Playwright / Appium）
|
||||
- 编写接口自动化测试脚本（pytest / JMeter / Postman）
|
||||
- 编写 UI 自动化测试脚本
|
||||
- 集成到 CI/CD 流水线，实现自动化回归
|
||||
- 维护自动化用例，保证脚本稳定性
|
||||
|
||||
### 2.4 性能测试
|
||||
- 制定性能测试方案，确定压测场景与指标
|
||||
- 使用 JMeter / Locust / k6 进行压力测试
|
||||
- 分析性能瓶颈（CPU/内存/IO/数据库慢查询）
|
||||
- 输出性能测试报告，给出优化建议
|
||||
- 生产环境容量评估与容量规划
|
||||
|
||||
### 2.5 安全测试
|
||||
- 执行安全扫描（OWASP Top 10）
|
||||
- SQL 注入、XSS、CSRF 等常见漏洞检测
|
||||
- API 接口权限验证、敏感数据泄露检查
|
||||
- 配合第三方安全公司进行渗透测试
|
||||
|
||||
### 2.6 质量度量
|
||||
- 统计缺陷密度、Bug 修复率、Bug 严重程度分布
|
||||
- 分析线上故障，推动故障复盘
|
||||
- 建立质量大盘，可视化质量趋势
|
||||
- 推动质量左移，提升提测质量
|
||||
|
||||
---
|
||||
|
||||
## 三、常用平台与工具
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **缺陷管理** | Jira | Bug 跟踪与管理 |
|
||||
| | 禅道 | 国产缺陷管理 |
|
||||
| | 飞书项目 | Bug 跟踪 |
|
||||
| | Bugzilla / Mantis | 开源缺陷管理 |
|
||||
| **测试管理** | TestRail | 测试用例管理 |
|
||||
| | Xray（Jira 插件） | 测试管理+Jira集成 |
|
||||
| | TestLink | 开源测试管理 |
|
||||
| | PingCode | 测试用例与计划 |
|
||||
| **接口测试** | Postman / Apifox | 手动接口调试 |
|
||||
| | REST Assured | Java 接口自动化 |
|
||||
| | pytest + requests | Python 接口自动化 |
|
||||
| | JMeter | 接口压力测试 |
|
||||
| **UI 自动化** | Selenium | Web 自动化 |
|
||||
| | Playwright | 新一代 Web 自动化 |
|
||||
| | Cypress | 前端 E2E 测试 |
|
||||
| | Appium | 移动端自动化 |
|
||||
| | Airtest | 移动端/游戏自动化 |
|
||||
| **性能测试** | JMeter | 接口压力测试 |
|
||||
| | Locust | Python 性能测试 |
|
||||
| | k6 | 云原生性能测试 |
|
||||
| | Gatling | Scala 性能测试 |
|
||||
| | wrk / ab | 轻量 HTTP 压测 |
|
||||
| **安全测试** | OWASP ZAP | Web 安全扫描 |
|
||||
| | Burp Suite | 渗透测试 |
|
||||
| | SQLMap | SQL 注入检测 |
|
||||
| | Nmap | 端口扫描 |
|
||||
| **抓包与调试** | Charles / Fiddler | HTTP 抓包 |
|
||||
| | Proxyman | Mac 代理调试 |
|
||||
| | Whistle | 跨平台抓包 |
|
||||
| **数据库** | Navicat / DBeaver | 数据库管理 |
|
||||
| | RedisInsight | Redis 可视化 |
|
||||
| **CI/CD 集成** | Jenkins / GitLab CI / GitHub Actions | 自动化测试流水线 |
|
||||
| | Allure | 测试报告可视化 |
|
||||
|
||||
---
|
||||
|
||||
## 四、测试流程
|
||||
|
||||
```
|
||||
需求评审 → 测试计划 → 用例设计 → 用例评审 → 冒烟测试 → 功能测试 → 回归测试 → 验收测试 → 上线
|
||||
│ │ │ │ │ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
|
||||
提出可测 测试策略 用例库 团队评审 版本准入 执行用例 Bug验证 UAT参与 测试报告
|
||||
性建议 资源排期 TestRail 对齐标准 快速验证 Bug提交 全量回归 验收签字 质量评估
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、测试策略分层（测试金字塔）
|
||||
|
||||
```
|
||||
╱ 〰 ╲
|
||||
╱ E2E ╲ 少量端到端测试（全链路验证）
|
||||
╱──────────────╲
|
||||
╱ 集成测试 ╲ 中量集成测试（模块联调、API）
|
||||
╱──────────────────╲
|
||||
╱ 单元测试 ╲ 大量单元测试（函数/类级别）
|
||||
╱──────────────────────────╲
|
||||
成本 ⬆️ ｜ 速度 ⬇️
|
||||
```
|
||||
|
||||
- **单元测试**：占 70%，开发编写，CI 自动运行
|
||||
- **接口/集成测试**：占 20%，测试+开发共同维护
|
||||
- **UI/E2E 测试**：占 10%，覆盖核心业务主流程
|
||||
|
||||
---
|
||||
|
||||
## 六、能力模型
|
||||
|
||||
| 级别 | 能力要求 |
|
||||
|------|----------|
|
||||
| **初级** | 执行功能测试，编写测试用例，提交 Bug |
|
||||
| **中级** | 独立负责模块测试，编写接口自动化脚本，性能测试执行 |
|
||||
| **高级** | 搭建自动化框架，主导性能/安全测试，制定测试策略 |
|
||||
| **资深** | 全链路质量体系搭建，测试左移/右移，团队赋能 |
|
||||
|
||||
| 通用能力 | 要求 |
|
||||
|----------|------|
|
||||
| 测试方法论 | 黑盒/白盒/灰盒、等价类、边界值、场景法 |
|
||||
| 编程能力 | Python/Java 至少一种，能写自动化脚本 |
|
||||
| SQL | 复杂查询、数据验证、造数据 |
|
||||
| Linux | 查看日志、部署服务、排查问题 |
|
||||
| 网络协议 | HTTP/HTTPS、TCP/IP、抓包分析 |
|
||||
| 业务理解 | 深度理解业务场景，设计有效用例 |
|
||||
| 细心与耐心 | 不放过任何一个异常现象 |
|
||||
|
||||
---
|
||||
|
||||
## 七、产出物清单
|
||||
|
||||
| 产出物 | 交付节点 |
|
||||
|--------|----------|
|
||||
| 测试计划 | 需求评审后 |
|
||||
| 测试用例 | 编码阶段 |
|
||||
| 冒烟测试报告 | 提测后 |
|
||||
| Bug 报告 | 测试过程中 |
|
||||
| 功能测试报告 | 测试完成 |
|
||||
| 性能测试报告 | 性能测试后 |
|
||||
| 安全测试报告 | 安全测试后 |
|
||||
| 自动化测试脚本 | 持续维护 |
|
||||
| 质量月报 | 每月 |
|
||||
@@ -1,117 +0,0 @@
|
||||
# 规划
|
||||
|
||||
> 所属公司：瑞来兹软件技术有限公司
|
||||
> 更新日期：2026-05-04
|
||||
|
||||
---
|
||||
|
||||
## 一、角色定义
|
||||
|
||||
规划岗位（含项目规划师、敏捷教练、技术规划等角色）负责项目的整体规划、资源调度和过程管控，确保项目按时、按质、按预算交付。
|
||||
|
||||
---
|
||||
|
||||
## 二、主要职责
|
||||
|
||||
### 2.1 项目规划
|
||||
- 制定项目章程（Project Charter），明确项目范围、目标、干系人
|
||||
- 编制 WBS（工作分解结构），拆解可执行的任务单元
|
||||
- 制定项目排期（甘特图），确定关键路径与里程碑
|
||||
- 评估项目风险，制定风险应对预案
|
||||
- 编制项目预算，跟踪成本与投入产出比
|
||||
|
||||
### 2.2 资源管理
|
||||
- 协调跨部门资源（研发、测试、设计、运维）
|
||||
- 制定人力投入计划，避免资源冲突
|
||||
- 管理外部供应商与外包团队
|
||||
- 项目物料与软硬件资源的采购跟进
|
||||
|
||||
### 2.3 进度管控
|
||||
- 主持项目例会（周会/日站会），跟踪任务进度
|
||||
- 使用燃尽图（Burndown Chart）监控 Sprint 健康度
|
||||
- 识别并解决阻塞项（Blocker），及时升级风险
|
||||
- 变更管理：评估变更影响，走 CR（Change Request）流程
|
||||
|
||||
### 2.4 质量与交付
|
||||
- 定义 DoD（Definition of Done），确保交付标准
|
||||
- 组织阶段评审（需求评审、设计评审、代码评审）
|
||||
- 管理 UAT 测试与验收交付
|
||||
- 项目结项：归档文档、复盘总结（Retrospective）
|
||||
|
||||
### 2.5 敏捷实践
|
||||
- 担任 Scrum Master，推动敏捷转型
|
||||
- 引导 Sprint Planning、Daily Standup、Sprint Review、Retro
|
||||
- 度量团队敏捷成熟度，持续优化流程
|
||||
- 培训团队敏捷/精益方法论
|
||||
|
||||
---
|
||||
|
||||
## 三、常用平台与工具
|
||||
|
||||
| 分类 | 工具 | 用途 |
|
||||
|------|------|------|
|
||||
| **项目管理** | Jira | Sprint 管理、任务跟踪、报表 |
|
||||
| | Microsoft Project | 专业项目排期、甘特图 |
|
||||
| | Asana | 轻量团队任务管理 |
|
||||
| | Monday.com | 可视化项目管理 |
|
||||
| | 禅道 | 国产全流程项目管理 |
|
||||
| | PingCode | 研发项目管理 |
|
||||
| | 飞书项目 | 飞书生态项目管理 |
|
||||
| | Teambition | 钉钉生态项目管理 |
|
||||
| | Worktile | 国产协作与项目管理 |
|
||||
| | OmniPlan | Mac 端专业甘特图 |
|
||||
| **文档与知识库** | Confluence | 项目文档 Wiki |
|
||||
| | Notion | 项目知识库 |
|
||||
| | 语雀 | 团队知识沉淀 |
|
||||
| **进度可视化** | 甘特图（Excel/Project） | 里程碑计划 |
|
||||
| | 燃尽图（Burndown） | Sprint 进度跟踪 |
|
||||
| | Miro / MURAL | 线上白板、Retro 回顾 |
|
||||
| **沟通协作** | 飞书 / 钉钉 / 企业微信 | 日常沟通 |
|
||||
| | Slack | 国际团队 |
|
||||
| | Zoom / 腾讯会议 | 远程会议 |
|
||||
| **文档处理** | Office 365 / WPS | 文档、表格、演示 |
|
||||
| | Google Workspace | 在线协作 |
|
||||
| **时间管理** | Toggl / Clockify | 工时记录 |
|
||||
| | RescueTime | 时间分析 |
|
||||
|
||||
---
|
||||
|
||||
## 四、关键流程
|
||||
|
||||
```
|
||||
项目立项 → 需求评审 → 方案设计 → Sprint规划 → 开发实施 → 测试验证 → UAT → 上线发布 → 结项复盘
|
||||
│ │ │ │ │ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
|
||||
立项书 PRD评审 技术方案 Sprint 每日站会 Bug跟踪 验收报告 发布清单 复盘报告
|
||||
评审 Backlog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、能力模型
|
||||
|
||||
| 能力 | 要求 |
|
||||
|------|------|
|
||||
| 项目管理 | PMP/PRINCE2/ACP 方法论、敏捷/瀑布混合 |
|
||||
| 风险管理 | 风险识别、概率评估、应对策略 |
|
||||
| 沟通协调 | 干系人管理、冲突解决、向上汇报 |
|
||||
| 时间管理 | 多项目并行管理、关键路径分析 |
|
||||
| 工具使用 | Jira/Project/甘特图等专业工具 |
|
||||
| 业务理解 | 快速理解行业背景与业务逻辑 |
|
||||
| 数据分析 | 项目度量指标、报表输出 |
|
||||
|
||||
---
|
||||
|
||||
## 六、产出物清单
|
||||
|
||||
| 产出物 | 交付节点 |
|
||||
|--------|----------|
|
||||
| 项目章程 | 立项阶段 |
|
||||
| WBS 工作分解 | 规划阶段 |
|
||||
| 项目排期（甘特图） | 规划阶段 |
|
||||
| 风险管理计划 | 规划阶段 |
|
||||
| 项目周报 | 每周 |
|
||||
| Sprint 燃尽图 | 每个 Sprint |
|
||||
| 阶段评审报告 | 里程碑节点 |
|
||||
| 变更申请单（CR） | 需求变更时 |
|
||||
| 项目复盘报告 | 结项 |
|
||||
Reference in New Issue
Block a user