worklog/doc/部署文档.md

工作日志服务平台 - 部署文档

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 目录结构

部署后的目录结构：

/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/                   # 前端静态资源目录
├── wladmin/                        # 管理后台
└── wlmobile/                       # 移动端 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 系统配置

# 文件描述符限制
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/wladmin
mkdir -p /var/www/worklog/wlmobile
mkdir -p /datacfs/applogs/worklog-api

3. 打包构建

3.1 全量打包

cd /path/to/worklog
./scripts/build-all.sh

打包产物输出到 deploy/ 目录。

3.2 单独打包

# 后端 API
cd worklog-api
mvn clean package -DskipTests

# 管理后台前端
./scripts/build-web.sh

# 移动端 H5
./scripts/build-mobile.sh

4. 部署步骤

4.1 部署后端服务

# 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 部署前端资源

# 管理后台
scp -r deploy/worklog-web/* user@server:/var/www/worklog/wladmin/

# 移动端 H5
scp -r deploy/worklog-mobile/* user@server:/var/www/worklog/wlmobile/

4.3 配置 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/wladmin;
        index index.html;
        try_files $uri $uri/ /wladmin/index.html;
    }

    # 移动端 H5
    location /wlmobile {
        alias /var/www/worklog/wlmobile;
        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;
    }
}

# 测试配置
nginx -t

# 重载配置
nginx -s reload

5. 配置说明

5.1 环境配置 (env.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)

# 服务名称
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 启动服务

./bin/start.sh

6.2 停止服务

./bin/stop.sh

6.3 重启服务

./bin/restart.sh

6.4 查看状态

./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 日志查看

# 实时查看应用日志
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 服务健康检查

# API 健康检查
curl http://localhost:8200/wlog/api/v1/health

# Swagger 文档
curl http://localhost:8200/wlog/swagger-ui.html

8.2 数据库连接检查

mysql -h localhost -u worklog -p'Wlog@123' -e "SELECT 1"

8.3 Redis 连接检查

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
• 需求规格说明书 SRS
• 架构设计文档
• 后端模块详细设计文档
• 前端详细设计文档