admin
b346b7e194
- Add a self-signed HTTPS Nginx entrypoint on Docker port 4443 so browser microphone APIs can run in demo mode. - Keep the existing HTTP port 4002 unchanged while exposing container port 443 and generating the demo certificate during image build. - Update CORS defaults and Compose environment for the HTTPS frontend origin. - Clarify the report editor microphone message with localhost, HTTPS, and browser trusted-origin demo options. - Document the browser HTTP microphone limitation, HTTPS demo URL, and Chrome/Edge insecure-origin workaround in README and docs.
233 lines
5.6 KiB
Markdown
233 lines
5.6 KiB
Markdown
# 安装与初始设置
|
||
|
||
本文档面向第一次接手项目的开发者，目标是把系统从源码启动到可登录、可保存报告。部署细节见 [部署运行](./deployment.md)，业务和架构背景见 [文档入口](./README.md)。
|
||
|
||
## 前置要求
|
||
|
||
- Node.js 20 或更高版本。
|
||
- npm。
|
||
- Docker 与 Docker Compose，用于一键启动 PostgreSQL、API 和前端。
|
||
- Linux/macOS shell 环境；Windows 建议使用 WSL。
|
||
|
||
确认工具可用：
|
||
|
||
```bash
|
||
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 前端 HTTPS 演示入口 | `4443` | 自签名证书入口，推荐用于麦克风听写 |
|
||
| Docker PostgreSQL | `5433` | 宿主机访问 Compose 数据库 |
|
||
|
||
如果这些端口被占用，优先修改 `.env`、`docker-compose.yaml` 和对应文档，避免回退到 `3000` 等默认端口。
|
||
|
||
## 推荐方式：Docker 一键启动
|
||
|
||
第一次启动：
|
||
|
||
```bash
|
||
npm install
|
||
docker compose up -d --build
|
||
```
|
||
|
||
启动后访问：
|
||
|
||
```text
|
||
http://localhost:4002
|
||
https://localhost:4443
|
||
```
|
||
|
||
健康检查：
|
||
|
||
```bash
|
||
curl http://localhost:4002/api/health
|
||
curl http://localhost:3002/api/health
|
||
```
|
||
|
||
当前 Compose 会启动：
|
||
|
||
- `tuwen_web`：Nginx 托管前端，宿主机端口 `4002`；同时提供自签名 HTTPS 演示入口 `4443`。
|
||
- `tuwen_api`：NestJS API，容器内监听 `3100`，宿主机端口 `3002`。
|
||
- `tuwen_db`：PostgreSQL 16，宿主机端口 `5433`。
|
||
|
||
查看状态：
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
停止：
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
连数据卷一起清理会删除数据库和上传文件，只在确认不需要当前数据时使用：
|
||
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
## 本地开发方式
|
||
|
||
如果希望前端热更新、后端直接跑在本机，可以按下面启动。
|
||
|
||
安装依赖并创建环境变量：
|
||
|
||
```bash
|
||
npm install
|
||
cp .env.example .env
|
||
```
|
||
|
||
先准备 PostgreSQL。可以复用 Compose 的数据库：
|
||
|
||
```bash
|
||
docker compose up -d db
|
||
```
|
||
|
||
生成 Prisma Client、执行迁移和 seed：
|
||
|
||
```bash
|
||
npm run prisma:generate
|
||
npm run prisma:migrate
|
||
npm run prisma:seed
|
||
```
|
||
|
||
启动后端 API：
|
||
|
||
```bash
|
||
npm run server:dev
|
||
```
|
||
|
||
API 默认地址：
|
||
|
||
```text
|
||
http://localhost:3100/api/health
|
||
```
|
||
|
||
另开一个终端启动前端开发服务：
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
前端开发地址：
|
||
|
||
```text
|
||
http://localhost:3001
|
||
```
|
||
|
||
开发模式下，Vite 会把 `/api` 代理到 `VITE_API_PROXY_TARGET`，默认是 `http://localhost:3100`。如果你想用本机 Vite 前端连接 Docker Compose API，把 `.env` 中的目标改成：
|
||
|
||
```bash
|
||
VITE_API_PROXY_TARGET="http://localhost:3002"
|
||
```
|
||
|
||
## 默认账号
|
||
|
||
默认数据由后端 seed 写入：
|
||
|
||
| 用户ID | 密码 | 角色 |
|
||
| --- | --- | --- |
|
||
| `admin` | `123456` | 超级管理员 |
|
||
| `manager` | `123456` | 管理员 |
|
||
| `0001` | `123456` | 医生 |
|
||
|
||
登录后建议先进入“系统设置”确认 AI Provider、讯飞语音配置、默认模板和抽帧策略。当前 demo mode 已内置演示用 AI 与语音配置；正式生产部署前必须替换或移除这些演示凭据，后续通过后端 Settings API 或正式密钥管理流程维护。
|
||
|
||
## 初次验收
|
||
|
||
完成启动后建议按顺序验证：
|
||
|
||
1. 打开 `http://localhost:4002`、语音演示地址 `https://localhost:4443` 或本地开发地址 `http://localhost:3001`。
|
||
2. 使用 `admin / 123456` 登录。
|
||
3. 进入工作台，确认统计卡片能正常加载。
|
||
4. 进入“系统设置”，确认全局配置可保存。
|
||
5. 使用医生账号 `0001 / 123456` 新建报告并保存草稿。
|
||
6. 进入“报告管理”，确认能看到刚保存的报告。
|
||
|
||
命令行验证：
|
||
|
||
```bash
|
||
npm run lint
|
||
npm run test
|
||
npm run build
|
||
```
|
||
|
||
后端、权限或关键流程变更后再运行：
|
||
|
||
```bash
|
||
npm run server:build
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 保存草稿提示后端不可用
|
||
|
||
先检查当前访问入口和 API 健康检查：
|
||
|
||
```bash
|
||
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`。
|
||
|
||
### 端口被占用
|
||
|
||
检查占用：
|
||
|
||
```bash
|
||
ss -ltnp | grep -E ':3001|:3002|:3100|:4002|:4443|:5433'
|
||
```
|
||
|
||
本项目不应使用 `3000` 作为默认 API 端口。如果必须改端口，同步修改 `.env`、`docker-compose.yaml`、`vite.config.ts` 或 Nginx upstream，并更新文档。
|
||
|
||
### 数据库连接失败
|
||
|
||
如果使用 Compose 数据库，确认 `tuwen_db` 正常运行：
|
||
|
||
```bash
|
||
docker compose ps db
|
||
```
|
||
|
||
本地默认连接串在 `.env.example` 中：
|
||
|
||
```text
|
||
postgresql://surclaw:surclaw_dev_password@localhost:5433/surclaw?schema=public
|
||
```
|
||
|
||
修改数据库配置后重新运行：
|
||
|
||
```bash
|
||
npm run prisma:generate
|
||
npm run prisma:migrate
|
||
npm run prisma:seed
|
||
```
|
||
|
||
### AI 或讯飞提示未配置
|
||
|
||
AI 对话和讯飞语音均通过后端代理读取系统设置。使用超级管理员进入“系统设置”，填写并保存 AI Provider、模型名称和讯飞 APPID/APIKey/APISecret。普通用户读取设置时不会拿到真实密钥。
|
||
|
||
### 前端页面像旧版本
|
||
|
||
Docker 重建后浏览器可能仍缓存旧 bundle。先强制刷新页面；仍异常时重新构建：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|