admin
e67763fa82
- Add docs/installation.md covering prerequisites, port usage, Docker startup, local development setup, default accounts, first-run validation, and common setup issues. - Link the installation guide from the project README and docs index. - Point deployment documentation to the installation guide for first-time setup. - Update AGENTS.md and progress documentation to include the new installation guide.
5.3 KiB
安装与初始设置
本文档面向第一次接手项目的开发者，目标是把系统从源码启动到可登录、可保存报告。部署细节见 部署运行，业务和架构背景见 文档入口。
前置要求
- Node.js 20 或更高版本。
- npm。
- Docker 与 Docker Compose，用于一键启动 PostgreSQL、API 和前端。
- Linux/macOS shell 环境；Windows 建议使用 WSL。
确认工具可用：
node --version
npm --version
docker --version
docker compose version
端口规划
本项目已避开常见默认端口：
| 用途 | 本地/宿主机端口 | 说明 |
|---|---|---|
| Vite 前端开发服务 | 3001 |
仅 npm run dev 使用 |
| NestJS API 本地服务 | 3100 |
npm run server:dev 默认监听 |
| Docker API 暴露端口 | 3002 |
宿主机访问 Compose API |
| Docker 前端入口 | 4002 |
推荐的整套系统访问入口 |
| Docker PostgreSQL | 5433 |
宿主机访问 Compose 数据库 |
如果这些端口被占用，优先修改 .env、docker-compose.yaml 和对应文档，避免回退到 3000 等默认端口。
推荐方式：Docker 一键启动
第一次启动：
npm install
docker compose up -d --build
启动后访问：
http://localhost:4002
健康检查：
curl http://localhost:4002/api/health
curl http://localhost:3002/api/health
当前 Compose 会启动：
tuwen_web：Nginx 托管前端，宿主机端口4002。tuwen_api：NestJS API，容器内监听3100，宿主机端口3002。tuwen_db：PostgreSQL 16，宿主机端口5433。
查看状态：
docker compose ps
停止：
docker compose down
连数据卷一起清理会删除数据库和上传文件，只在确认不需要当前数据时使用：
docker compose down -v
本地开发方式
如果希望前端热更新、后端直接跑在本机，可以按下面启动。
安装依赖并创建环境变量：
npm install
cp .env.example .env
先准备 PostgreSQL。可以复用 Compose 的数据库：
docker compose up -d db
生成 Prisma Client、执行迁移和 seed：
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed
启动后端 API：
npm run server:dev
API 默认地址：
http://localhost:3100/api/health
另开一个终端启动前端开发服务：
npm run dev
前端开发地址：
http://localhost:3001
开发模式下，Vite 会把 /api 代理到 VITE_API_PROXY_TARGET，默认是 http://localhost:3100。如果你想用本机 Vite 前端连接 Docker Compose API，把 .env 中的目标改成：
VITE_API_PROXY_TARGET="http://localhost:3002"
默认账号
默认数据由后端 seed 写入：
| 用户ID | 密码 | 角色 |
|---|---|---|
admin |
123456 |
超级管理员 |
manager |
123456 |
管理员 |
0001 |
123456 |
医生 |
登录后建议先进入“系统设置”确认 AI Provider、讯飞语音配置、默认模板和抽帧策略。AI 与语音密钥保存在后端 Settings API 中，不应写入源码、文档或提交记录。
初次验收
完成启动后建议按顺序验证：
- 打开
http://localhost:4002或本地开发地址http://localhost:3001。 - 使用
admin / 123456登录。 - 进入工作台，确认统计卡片能正常加载。
- 进入“系统设置”，确认全局配置可保存。
- 使用医生账号
0001 / 123456新建报告并保存草稿。 - 进入“报告管理”，确认能看到刚保存的报告。
命令行验证：
npm run lint
npm run test
npm run build
后端、权限或关键流程变更后再运行：
npm run server:build
npm run test:e2e
常见问题
保存草稿提示后端不可用
先检查当前访问入口和 API 健康检查：
curl http://localhost:4002/api/health
curl http://localhost:3002/api/health
docker compose ps
Docker 方式应访问 http://localhost:4002。本地开发方式应确保 npm run server:dev 正在运行，并且 VITE_API_PROXY_TARGET 指向 http://localhost:3100。
端口被占用
检查占用：
ss -ltnp | grep -E ':3001|:3002|:3100|:4002|:5433'
本项目不应使用 3000 作为默认 API 端口。如果必须改端口，同步修改 .env、docker-compose.yaml、vite.config.ts 或 Nginx upstream，并更新文档。
数据库连接失败
如果使用 Compose 数据库，确认 tuwen_db 正常运行：
docker compose ps db
本地默认连接串在 .env.example 中：
postgresql://surclaw:surclaw_dev_password@localhost:5433/surclaw?schema=public
修改数据库配置后重新运行：
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed
AI 或讯飞提示未配置
AI 对话和讯飞语音均通过后端代理读取系统设置。使用超级管理员进入“系统设置”，填写并保存 AI Provider、模型名称和讯飞 APPID/APIKey/APISecret。普通用户读取设置时不会拿到真实密钥。
前端页面像旧版本
Docker 重建后浏览器可能仍缓存旧 bundle。先强制刷新页面；仍异常时重新构建：
docker compose up -d --build