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

## 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/                   # 前端静态资源目录
├── 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 系统配置

```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/wladmin
mkdir -p /var/www/worklog/wlmobile
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/wladmin/

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

### 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/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;
    }
}
```

```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)