docs: 添加部署文档
包含以下内容： - 系统架构图 - 部署产物说明 - 环境要求 - 打包构建步骤 - 部署步骤（后端、前端、Nginx） - 配置说明 - 启停脚本使用 - 日志说明 - 健康检查 - 常见问题
This commit is contained in:
zhangjf
parent
3161cbb429
commit
51cb742271
421
doc/部署文档.md
Normal file
421
doc/部署文档.md
Normal file
@ -0,0 +1,421 @@
|
|||||||
|
# 工作日志服务平台 - 部署文档
|
||||||
|
|
||||||
|
## 1. 部署概述
|
||||||
|
|
||||||
|
### 1.1 系统架构
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ Nginx (80/443) │
|
||||||
|
├──────────────────┬──────────────────┬───────────────────────┤
|
||||||
|
│ /wladmin/* │ /wlmobile/* │ /wlog/api/* │
|
||||||
|
│ 管理后台 │ 移动端H5 │ 后端API │
|
||||||
|
└──────────────────┴──────────────────┴───────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ worklog-api (端口 8200) │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Spring Boot 3.2 + MyBatis-Plus + Redis │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────┼───────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌────────┐ ┌────────┐ ┌────────┐
|
||||||
|
│ MySQL │ │ Redis │ │ Nacos │
|
||||||
|
│ 3306 │ │ 6379 │ │ 8848 │
|
||||||
|
└────────┘ └────────┘ └────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2 部署产物
|
||||||
|
|
||||||
|
| 产物 | 说明 | 大小 |
|
||||||
|
|------|------|------|
|
||||||
|
| worklog-api.tar.gz | 后端 API 服务 | ~45MB |
|
||||||
|
| worklog-web/ | 管理后台前端静态资源 | ~1.6MB |
|
||||||
|
| worklog-mobile/ | 移动端 H5 静态资源 | ~632KB |
|
||||||
|
|
||||||
|
### 1.3 目录结构
|
||||||
|
|
||||||
|
部署后的目录结构：
|
||||||
|
|
||||||
|
```text
|
||||||
|
/opt/worklog/worklog-api/ # 后端应用目录
|
||||||
|
├── bin/ # 脚本目录
|
||||||
|
│ ├── start.sh # 启动脚本
|
||||||
|
│ ├── stop.sh # 停止脚本
|
||||||
|
│ ├── restart.sh # 重启脚本
|
||||||
|
│ └── status.sh # 状态查看脚本
|
||||||
|
├── lib/ # JAR 包目录
|
||||||
|
│ ├── worklog-api-1.0.0.jar # 应用 JAR (瘦包)
|
||||||
|
│ └── *.jar # 依赖 JAR
|
||||||
|
└── conf/ # 配置文件目录
|
||||||
|
├── application.yml # 主配置
|
||||||
|
├── logback-spring.xml # 日志配置
|
||||||
|
├── env.properties # 环境配置
|
||||||
|
└── service.properties # 服务配置
|
||||||
|
|
||||||
|
/var/www/worklog/ # 前端静态资源目录
|
||||||
|
├── admin/ # 管理后台
|
||||||
|
└── mobile/ # 移动端 H5
|
||||||
|
|
||||||
|
/datacfs/applogs/worklog-api/ # 日志目录
|
||||||
|
├── app.log # 应用主日志
|
||||||
|
├── sql.log # SQL 日志
|
||||||
|
├── stdout.log # 控制台输出
|
||||||
|
├── gc.log # GC 日志
|
||||||
|
└── heapdump.hprof # 内存溢出快照（异常时生成）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 环境要求
|
||||||
|
|
||||||
|
### 2.1 基础环境
|
||||||
|
|
||||||
|
| 组件 | 版本要求 | 说明 |
|
||||||
|
|------|----------|------|
|
||||||
|
| JDK | 21+ | Java 运行环境 |
|
||||||
|
| MySQL | 8.0+ | 数据库 |
|
||||||
|
| Redis | 6.0+ | 缓存服务 |
|
||||||
|
| Nginx | 1.20+ | Web 服务器 |
|
||||||
|
| Nacos | 2.0+ | 注册/配置中心（可选） |
|
||||||
|
|
||||||
|
### 2.2 系统配置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 文件描述符限制
|
||||||
|
echo "* soft nofile 65535" >> /etc/security/limits.conf
|
||||||
|
echo "* hard nofile 65535" >> /etc/security/limits.conf
|
||||||
|
|
||||||
|
# 创建部署目录
|
||||||
|
mkdir -p /opt/worklog/worklog-api
|
||||||
|
mkdir -p /var/www/worklog/admin
|
||||||
|
mkdir -p /var/www/worklog/mobile
|
||||||
|
mkdir -p /datacfs/applogs/worklog-api
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 打包构建
|
||||||
|
|
||||||
|
### 3.1 全量打包
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /path/to/worklog
|
||||||
|
./scripts/build-all.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
打包产物输出到 `deploy/` 目录。
|
||||||
|
|
||||||
|
### 3.2 单独打包
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 后端 API
|
||||||
|
cd worklog-api
|
||||||
|
mvn clean package -DskipTests
|
||||||
|
|
||||||
|
# 管理后台前端
|
||||||
|
./scripts/build-web.sh
|
||||||
|
|
||||||
|
# 移动端 H5
|
||||||
|
./scripts/build-mobile.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. 部署步骤
|
||||||
|
|
||||||
|
### 4.1 部署后端服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 上传并解压
|
||||||
|
scp deploy/worklog-api.tar.gz user@server:/opt/worklog/
|
||||||
|
ssh user@server
|
||||||
|
cd /opt/worklog
|
||||||
|
tar -xzf worklog-api.tar.gz
|
||||||
|
|
||||||
|
# 2. 修改配置
|
||||||
|
cd worklog-api/conf
|
||||||
|
vi env.properties # 修改数据库、Redis 等配置
|
||||||
|
|
||||||
|
# 3. 启动服务
|
||||||
|
cd ../bin
|
||||||
|
./start.sh
|
||||||
|
|
||||||
|
# 4. 检查状态
|
||||||
|
./status.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 部署前端资源
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 管理后台
|
||||||
|
scp -r deploy/worklog-web/* user@server:/var/www/worklog/admin/
|
||||||
|
|
||||||
|
# 移动端 H5
|
||||||
|
scp -r deploy/worklog-mobile/* user@server:/var/www/worklog/mobile/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 配置 Nginx
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
# /etc/nginx/conf.d/worklog.conf
|
||||||
|
|
||||||
|
upstream worklog-api {
|
||||||
|
server 127.0.0.1:8200;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name worklog.example.com;
|
||||||
|
|
||||||
|
# 管理后台
|
||||||
|
location /wladmin {
|
||||||
|
alias /var/www/worklog/admin;
|
||||||
|
index index.html;
|
||||||
|
try_files $uri $uri/ /wladmin/index.html;
|
||||||
|
}
|
||||||
|
|
||||||
|
# 移动端 H5
|
||||||
|
location /wlmobile {
|
||||||
|
alias /var/www/worklog/mobile;
|
||||||
|
index index.html;
|
||||||
|
try_files $uri $uri/ /wlmobile/index.html;
|
||||||
|
}
|
||||||
|
|
||||||
|
# 后端 API - 管理后台
|
||||||
|
location /wladmin/api/ {
|
||||||
|
proxy_pass http://worklog-api/wlog/api/;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
}
|
||||||
|
|
||||||
|
# 后端 API - 移动端
|
||||||
|
location /wlmobile/api/ {
|
||||||
|
proxy_pass http://worklog-api/wlog/api/;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
}
|
||||||
|
|
||||||
|
# Swagger API 文档
|
||||||
|
location /wlog {
|
||||||
|
proxy_pass http://worklog-api/wlog;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 测试配置
|
||||||
|
nginx -t
|
||||||
|
|
||||||
|
# 重载配置
|
||||||
|
nginx -s reload
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. 配置说明
|
||||||
|
|
||||||
|
### 5.1 环境配置 (env.properties)
|
||||||
|
|
||||||
|
```properties
|
||||||
|
# ==================== 数据库配置 ====================
|
||||||
|
DB_HOST=localhost
|
||||||
|
DB_PORT=3306
|
||||||
|
DB_NAME=worklog
|
||||||
|
DB_USERNAME=worklog
|
||||||
|
DB_PASSWORD=Wlog@123
|
||||||
|
|
||||||
|
# ==================== Redis 配置 ====================
|
||||||
|
REDIS_HOST=localhost
|
||||||
|
REDIS_PORT=6379
|
||||||
|
REDIS_PASSWORD=zjf@123456
|
||||||
|
REDIS_DATABASE=0
|
||||||
|
|
||||||
|
# ==================== 日志配置 ====================
|
||||||
|
LOG_PATH=/datacfs/applogs/worklog-api
|
||||||
|
LOG_LEVEL_ROOT=INFO
|
||||||
|
LOG_LEVEL_APP=DEBUG
|
||||||
|
|
||||||
|
# ==================== JVM 配置 ====================
|
||||||
|
JVM_XMS=512m
|
||||||
|
JVM_XMX=1024m
|
||||||
|
JVM_METASPACE_SIZE=128m
|
||||||
|
JVM_MAX_METASPACE_SIZE=256m
|
||||||
|
JVM_GC_TYPE=G1GC
|
||||||
|
|
||||||
|
# ==================== 腾讯云 COS（可选）====================
|
||||||
|
COS_ENABLED=false
|
||||||
|
COS_APP_ID=your-app-id
|
||||||
|
COS_SECRET_ID=your-secret-id
|
||||||
|
COS_SECRET_KEY=your-secret-key
|
||||||
|
COS_BUCKET_NAME=your-bucket
|
||||||
|
COS_REGION=ap-beijing
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 服务配置 (service.properties)
|
||||||
|
|
||||||
|
```properties
|
||||||
|
# 服务名称
|
||||||
|
APP_NAME=worklog-api
|
||||||
|
|
||||||
|
# 主启动类
|
||||||
|
MAIN_CLASS=com.wjbl.worklog.WorklogApplication
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 主配置 (application.yml)
|
||||||
|
|
||||||
|
主要配置项说明：
|
||||||
|
|
||||||
|
| 配置项 | 默认值 | 说明 |
|
||||||
|
|--------|--------|------|
|
||||||
|
| server.port | 8200 | 服务端口 |
|
||||||
|
| server.servlet.context-path | /wlog | API 根路径 |
|
||||||
|
|
||||||
|
## 6. 启停脚本
|
||||||
|
|
||||||
|
### 6.1 启动服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./bin/start.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 停止服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./bin/stop.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.3 重启服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./bin/restart.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.4 查看状态
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./bin/status.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
输出示例：
|
||||||
|
|
||||||
|
```
|
||||||
|
========================================
|
||||||
|
应用状态: 运行中
|
||||||
|
PID: 12345
|
||||||
|
启动时间: 2024-01-01 10:00:00
|
||||||
|
运行时长: 2小时30分钟
|
||||||
|
CPU 占用: 5.2%
|
||||||
|
内存占用: 512MB
|
||||||
|
端口监听: 8200
|
||||||
|
========================================
|
||||||
|
最近日志:
|
||||||
|
[2024-01-01 12:30:00] INFO - 应用运行正常
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7. 日志说明
|
||||||
|
|
||||||
|
### 7.1 日志文件
|
||||||
|
|
||||||
|
| 文件 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| app.log | 应用主日志，包含所有级别日志 |
|
||||||
|
| sql.log | MyBatis-Plus SQL 日志 |
|
||||||
|
| stdout.log | 控制台标准输出 |
|
||||||
|
| gc.log | JVM GC 日志 |
|
||||||
|
| heapdump.hprof | 内存溢出快照（异常时生成） |
|
||||||
|
|
||||||
|
### 7.2 日志格式
|
||||||
|
|
||||||
|
所有日志包含链路追踪字段：
|
||||||
|
|
||||||
|
```
|
||||||
|
2024-01-01 12:00:00.000 [http-nio-8200-exec-1] [abc123][def456] INFO c.w.c.UserController - 用户登录成功
|
||||||
|
```
|
||||||
|
|
||||||
|
- `abc123`: traceId（链路追踪ID）
|
||||||
|
- `def456`: spanId（跨度ID）
|
||||||
|
|
||||||
|
### 7.3 日志查看
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 实时查看应用日志
|
||||||
|
tail -f /datacfs/applogs/worklog-api/app.log
|
||||||
|
|
||||||
|
# 查看 SQL 日志
|
||||||
|
tail -f /datacfs/applogs/worklog-api/sql.log
|
||||||
|
|
||||||
|
# 查看启动日志
|
||||||
|
tail -f /datacfs/applogs/worklog-api/stdout.log
|
||||||
|
|
||||||
|
# 按链路追踪
|
||||||
|
grep "abc123" /datacfs/applogs/worklog-api/app.log
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. 健康检查
|
||||||
|
|
||||||
|
### 8.1 服务健康检查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# API 健康检查
|
||||||
|
curl http://localhost:8200/wlog/api/v1/health
|
||||||
|
|
||||||
|
# Swagger 文档
|
||||||
|
curl http://localhost:8200/wlog/swagger-ui.html
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 数据库连接检查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mysql -h localhost -u worklog -p'Wlog@123' -e "SELECT 1"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.3 Redis 连接检查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
redis-cli -h localhost -p 6379 -a 'zjf@123456' ping
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. 常见问题
|
||||||
|
|
||||||
|
### 9.1 服务启动失败
|
||||||
|
|
||||||
|
1. 检查日志文件 `stdout.log`
|
||||||
|
2. 检查配置文件是否正确
|
||||||
|
3. 检查端口是否被占用：`netstat -tlnp | grep 8200`
|
||||||
|
4. 检查数据库连接是否正常
|
||||||
|
|
||||||
|
### 9.2 内存溢出
|
||||||
|
|
||||||
|
1. 查看堆内存快照：`/datacfs/applogs/worklog-api/heapdump.hprof`
|
||||||
|
2. 调整 JVM 参数：修改 `env.properties` 中的 `JVM_XMX`
|
||||||
|
|
||||||
|
### 9.3 数据库连接失败
|
||||||
|
|
||||||
|
1. 检查数据库服务是否启动
|
||||||
|
2. 检查用户名密码是否正确
|
||||||
|
3. 检查数据库是否授权远程访问
|
||||||
|
|
||||||
|
## 10. 附录
|
||||||
|
|
||||||
|
### 10.1 默认账号
|
||||||
|
|
||||||
|
| 系统 | 用户名 | 密码 |
|
||||||
|
|------|--------|------|
|
||||||
|
| 管理后台 | admin | admin123 |
|
||||||
|
|
||||||
|
### 10.2 端口列表
|
||||||
|
|
||||||
|
| 服务 | 端口 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| worklog-api | 8200 | 后端 API |
|
||||||
|
| MySQL | 3306 | 数据库 |
|
||||||
|
| Redis | 6379 | 缓存 |
|
||||||
|
| Nacos | 8848 | 注册/配置中心 |
|
||||||
|
| Nginx | 80/443 | Web 服务器 |
|
||||||
|
|
||||||
|
### 10.3 相关文档
|
||||||
|
|
||||||
|
- [产品需求文档 PRD](./产品需求文档PRD.md)
|
||||||
|
- [需求规格说明书 SRS](./需求规格说明书SRS.md)
|
||||||
|
- [架构设计文档](./架构设计文档.md)
|
||||||
|
- [后端模块详细设计文档](./后端模块详细设计文档.md)
|
||||||
|
- [前端详细设计文档](./前端详细设计文档.md)
|
||||||
Loading…
x
Reference in New Issue
Block a user