207 lines
5.5 KiB
Markdown
207 lines
5.5 KiB
Markdown
# 快速启动指南
|
||
|
||
## 一、数据库初始化
|
||
|
||
### 方式 1: 使用自动化脚本（推荐）
|
||
|
||
```powershell
|
||
# 在项目根目录执行
|
||
.\scripts\init-db.ps1
|
||
```
|
||
|
||
脚本会自动完成:
|
||
1. 创建 `back_cover` 数据库
|
||
2. 提示你首次启动应用以创建表结构（Ent ORM 自动迁移）
|
||
3. 插入种子数据（用户、设备、产品类型等）
|
||
|
||
### 方式 2: 手动初始化
|
||
|
||
```powershell
|
||
# 1. 创建数据库
|
||
psql -U postgres -c "CREATE DATABASE back_cover;"
|
||
|
||
# 2. 首次启动应用（自动创建表结构）
|
||
cd d:\hardman\back_cover
|
||
go run hougai.go -f etc/hougai-api.yaml
|
||
# 等待看到 "Starting server at..." 后按 Ctrl+C 停止
|
||
|
||
# 3. 插入种子数据
|
||
psql -U postgres -d back_cover -f doc/data.sql
|
||
|
||
# 4. 重启应用
|
||
go run hougai.go -f etc/hougai-api.yaml
|
||
```
|
||
|
||
### 默认管理员账号
|
||
|
||
- **用户名**: admin
|
||
- **密码**: 123456
|
||
|
||
---
|
||
|
||
## 二、启动管理后台
|
||
|
||
### 方式 1: VS Code 一键启动（推荐）
|
||
|
||
1. 用 VS Code 打开项目根目录
|
||
2. 按 `Ctrl+Shift+P`，选择 **"Tasks: Run Task"**
|
||
3. 选择 **"Start Full Stack"**
|
||
- 这会同时启动后端 API 服务（端口 8888）和前端开发服务器（端口 7070）
|
||
4. 浏览器会自动打开登录页面
|
||
|
||
### 方式 2: 手动启动
|
||
|
||
#### 启动后端
|
||
|
||
```powershell
|
||
cd d:\hardman\back_cover
|
||
go run hougai.go -f etc/hougai-api.yaml
|
||
```
|
||
|
||
后端服务将运行在: `http://localhost:8888`
|
||
|
||
#### 启动前端（新终端窗口）
|
||
|
||
```powershell
|
||
cd d:\hardman\back_cover\frontend
|
||
pnpm install # 首次运行需要
|
||
pnpm dev
|
||
```
|
||
|
||
前端开发服务器将运行在: `http://localhost:7070`
|
||
|
||
浏览器访问: `http://localhost:7070`
|
||
|
||
---
|
||
|
||
## 三、VS Code 调试配置
|
||
|
||
已为你配置好 `.vscode/launch.json`，包含以下调试选项:
|
||
|
||
### 1. 单独调试后端
|
||
|
||
- 按 `F5` 或点击 VS Code 左侧的"运行和调试"
|
||
- 选择 **"Backend: hougai-api"**
|
||
- 点击绿色播放按钮
|
||
|
||
### 2. 单独调试前端
|
||
|
||
- 选择 **"Frontend: dev server"**
|
||
- 确保前端开发服务器已运行
|
||
- 点击绿色播放按钮（会打开 Chrome 浏览器并附加调试）
|
||
|
||
### 3. 完整栈调试
|
||
|
||
- 选择 **"Full Stack: Start Backend + Frontend"**
|
||
- 会自动启动后端和前端，并在服务就绪时打开浏览器
|
||
|
||
---
|
||
|
||
## 四、常见问题
|
||
|
||
### Q1: psql 命令找不到
|
||
|
||
**错误信息**: `未找到 psql 命令`
|
||
|
||
**解决方法**:
|
||
1. 安装 PostgreSQL: https://www.postgresql.org/download/windows/
|
||
2. 确保 `psql` 在系统 PATH 中（安装时勾选"Add to PATH")
|
||
3. 重启终端
|
||
|
||
### Q2: 数据库连接失败
|
||
|
||
**错误信息**: `could not connect to server: Connection refused`
|
||
|
||
**解决方法**:
|
||
1. 检查 PostgreSQL 服务是否运行
|
||
- Windows: `services.msc` → 查找 "postgresql-x64-*" 服务 → 确保正在运行
|
||
2. 检查端口是否正确（默认 5432）
|
||
3. 检查配置文件 `etc/hougai-api.yaml` 中的数据库连接参数
|
||
|
||
### Q3: 前端无法连接后端
|
||
|
||
**错误信息**: `Network Error` 或 CORS 错误
|
||
|
||
**解决方法**:
|
||
1. 确保后端服务正在运行（端口 8888）
|
||
2. 检查 `frontend/vite.config.ts` 中的代理配置
|
||
3. 清除浏览器缓存并重试
|
||
|
||
### Q4: Ent ORM 表结构创建失败
|
||
|
||
**错误信息**: 各种 ent 相关错误
|
||
|
||
**解决方法**:
|
||
1. 确认 PostgreSQL 版本 >= 12
|
||
2. 检查数据库用户权限（需要 CREATE 权限）
|
||
3. 尝试手动删除数据库重建:
|
||
```powershell
|
||
psql -U postgres -c "DROP DATABASE IF EXISTS back_cover;"
|
||
psql -U postgres -c "CREATE DATABASE back_cover;"
|
||
go run hougai.go -f etc/hougai-api.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 五、其他有用命令
|
||
|
||
### 清理数据库种子数据
|
||
|
||
```powershell
|
||
psql -U postgres -d back_cover -f doc/reset.sql
|
||
```
|
||
|
||
### 查看数据库表结构
|
||
|
||
```powershell
|
||
psql -U postgres -d back_cover -c "\dt" # 查看所有表
|
||
psql -U postgres -d back_cover -c "\d equipment" # 查看 equipment 表结构
|
||
```
|
||
|
||
### 查询测试数据
|
||
|
||
```powershell
|
||
psql -U postgres -d back_cover -c "SELECT * FROM user;" # 查询所有用户
|
||
psql -U postgres -d back_cover -c "SELECT id, name, equipment_type_id FROM equipment;" # 查询所有设备
|
||
psql -U postgres -d back_cover -c "SELECT * FROM product_type WHERE is_active = true;" # 查询活跃产品类型
|
||
```
|
||
|
||
---
|
||
|
||
## 六、技术架构概要
|
||
|
||
```
|
||
┌─────────────────┐ ┌──────────────────┐
|
||
│ 前端 (React) │◄──────►│ 后端 (Go) │
|
||
│ :7070 (Vite) │ HTTP │ :8888 (go-zero) │
|
||
└─────────────────┘ └────────┬─────────┘
|
||
│
|
||
│ pgx driver
|
||
▼
|
||
┌─────────────────┐
|
||
│ PostgreSQL 12+ │
|
||
│ database: │
|
||
│ back_cover │
|
||
└─────────────────┘
|
||
```
|
||
|
||
- **前端**: React 19 + TypeScript + Vite + Semi Design
|
||
- **后端**: Go 1.25 + go-zero + Ent ORM
|
||
- **数据库**: PostgreSQL 12+
|
||
- **通信**: REST API + SSE (Server-Sent Events)
|
||
|
||
---
|
||
|
||
## 七、下一步
|
||
|
||
1. ✅ 完成数据库初始化
|
||
2. ✅ 启动后端和前端服务
|
||
3. ✅ 浏览器登录管理后台 (`http://localhost:7070`)
|
||
4. 📖 阅读项目文档: `系统设计方案.md`
|
||
5. 🔧 探索功能模块和设备配置
|
||
|
||
如有问题，请查看日志文件:
|
||
- 后端日志: `hougai.log`
|
||
- 浏览器控制台: F12 → Console
|
||
- 网络请求: F12 → Network
|