diff --git a/doc/部署文档.md b/doc/部署文档.md new file mode 100644 index 0000000..987c928 --- /dev/null +++ b/doc/部署文档.md @@ -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)