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