makemd/docs/03_Deployment_Guide.md

# 部署指南

## 1. 环境要求

### 1.1 硬件要求
- **CPU**: 至少 2 核
- **内存**: 至少 4GB
- **磁盘**: 至少 50GB 可用空间

### 1.2 软件要求
- **Java**: JDK 17 或更高版本
- **MySQL**: 8.0 或更高版本
- **Redis**: 6.0 或更高版本
- **Maven**: 3.6 或更高版本

## 2. 安装步骤

### 2.1 安装 Java

**Windows 系统**:
1. 下载 JDK 17 安装包：[Oracle JDK 17](https://www.oracle.com/java/technologies/downloads/#java17)
2. 运行安装包，按照提示完成安装
3. 配置环境变量：
   - 右键点击「此电脑」→「属性」→「高级系统设置」→「环境变量」
   - 在「系统变量」中添加 `JAVA_HOME`，值为 JDK 安装目录
   - 在「系统变量」的 `Path` 中添加 `%JAVA_HOME%\bin`
4. 验证安装：打开命令提示符，运行 `java -version`，显示 JDK 版本信息

**Linux 系统**:
1. 下载 JDK 17 安装包：
   ```bash
   wget https://download.oracle.com/java/17/latest/jdk-17_linux-x64_bin.rpm
   ```
2. 安装 JDK：
   ```bash
   sudo rpm -ivh jdk-17_linux-x64_bin.rpm
   ```
3. 验证安装：
   ```bash
   java -version
   ```

### 2.2 安装 MySQL

**Windows 系统**:
1. 下载 MySQL 8.0 安装包：[MySQL Community Server](https://dev.mysql.com/downloads/mysql/)
2. 运行安装包，按照提示完成安装
3. 配置 MySQL：
   - 启动 MySQL 服务
   - 登录 MySQL，修改 root 密码
   - 创建数据库：`CREATE DATABASE crawlful_hub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

**Linux 系统**:
1. 安装 MySQL：
   ```bash
   sudo yum install mysql-server
   ```
2. 启动 MySQL 服务：
   ```bash
   sudo systemctl start mysqld
   ```
3. 配置 MySQL：
   ```bash
   sudo mysql_secure_installation
   ```
4. 创建数据库：
   ```bash
   mysql -u root -p
   CREATE DATABASE crawlful_hub CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

### 2.3 安装 Redis

**Windows 系统**:
1. 下载 Redis 安装包：[Redis for Windows](https://github.com/tporadowski/redis/releases)
2. 运行安装包，按照提示完成安装
3. 启动 Redis 服务：
   ```bash
   redis-server
   ```

**Linux 系统**:
1. 安装 Redis：
   ```bash
   sudo yum install redis
   ```
2. 启动 Redis 服务：
   ```bash
   sudo systemctl start redis
   ```

### 2.4 安装 Maven

**Windows 系统**:
1. 下载 Maven 安装包：[Apache Maven](https://maven.apache.org/download.cgi)
2. 解压安装包到指定目录
3. 配置环境变量：
   - 右键点击「此电脑」→「属性」→「高级系统设置」→「环境变量」
   - 在「系统变量」中添加 `MAVEN_HOME`，值为 Maven 安装目录
   - 在「系统变量」的 `Path` 中添加 `%MAVEN_HOME%\bin`
4. 验证安装：打开命令提示符，运行 `mvn -version`，显示 Maven 版本信息

**Linux 系统**:
1. 安装 Maven：
   ```bash
   sudo yum install maven
   ```
2. 验证安装：
   ```bash
   mvn -version
   ```

## 3. 项目配置

### 3.1 数据库配置

编辑 `src/main/resources/application.yml` 文件，修改数据库连接信息：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/crawlful_hub?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
```

### 3.2 Redis 配置

编辑 `src/main/resources/application.yml` 文件，修改 Redis 连接信息：

```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password:
    database: 0
```

### 3.3 JWT 配置

编辑 `src/main/resources/application.yml` 文件，修改 JWT 配置：

```yaml
spring:
  security:
    jwt:
      secret: your-secret-key
      expiration: 86400000
```

### 3.4 服务器配置

编辑 `src/main/resources/application.yml` 文件，修改服务器配置：

```yaml
server:
  port: 3001
  servlet:
    context-path: /api
```

## 4. 构建与部署

### 4.1 构建项目

1. 进入项目目录：
   ```bash
   cd d:\trae_projects\makemd\makemd\serverjava
   ```

2. 执行 Maven 构建：
   ```bash
   mvn clean package
   ```

3. 构建成功后，在 `target` 目录中生成 `serverjava-0.0.1-SNAPSHOT.jar` 文件。

### 4.2 运行项目

**方法一：直接运行**

1. 进入 `target` 目录：
   ```bash
   cd target
   ```

2. 运行 jar 文件：
   ```bash
   java -jar serverjava-0.0.1-SNAPSHOT.jar
   ```

**方法二：作为服务运行**

**Windows 系统**:
1. 创建服务脚本：
   ```batch
   @echo off
   set JAVA_HOME=C:\Program Files\Java\jdk-17
   set PATH=%JAVA_HOME%\bin;%PATH%
   java -jar d:\trae_projects\makemd\makemd\serverjava\target\serverjava-0.0.1-SNAPSHOT.jar
   ```

2. 将脚本保存为 `serverjava.bat`，然后运行。

**Linux 系统**:
1. 创建服务文件：
   ```bash
   sudo nano /etc/systemd/system/serverjava.service
   ```

2. 添加以下内容：
   ```
   [Unit]
   Description=ServerJava Service
   After=network.target

   [Service]
   Type=simple
   User=root
   ExecStart=/usr/bin/java -jar /path/to/serverjava/target/serverjava-0.0.1-SNAPSHOT.jar
   Restart=on-failure

   [Install]
   WantedBy=multi-user.target
   ```

3. 启动服务：
   ```bash
   sudo systemctl start serverjava
   sudo systemctl enable serverjava
   ```

## 5. 验证部署

1. 打开浏览器，访问 `http://localhost:3001/api/api-docs`，查看 API 文档。

2. 访问 `http://localhost:3001/api/v1/monitoring/health`，查看系统健康状态。

3. 访问 `http://localhost:3001/api/v1/monitoring/ping`，测试系统响应。

## 6. 日志管理

### 6.1 日志配置

编辑 `src/main/resources/logback.xml` 文件，修改日志配置：

```xml
<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/server.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>logs/server.%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="info">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="FILE" />
  </root>
</configuration>
```

### 6.2 日志查看

**Windows 系统**:
1. 进入项目目录，查看日志文件：
   ```bash
   cd d:\trae_projects\makemd\makemd\serverjava
   type logs\server.log
   ```

**Linux 系统**:
1. 进入项目目录，查看日志文件：
   ```bash
   cd /path/to/serverjava
   tail -f logs/server.log
   ```

## 7. 故障排查

### 7.1 常见问题

1. **数据库连接失败**
   - 检查数据库服务是否运行
   - 检查数据库连接配置是否正确
   - 检查数据库用户权限是否正确

2. **Redis 连接失败**
   - 检查 Redis 服务是否运行
   - 检查 Redis 连接配置是否正确

3. **端口被占用**
   - 检查端口是否被其他服务占用
   - 修改 `application.yml` 中的端口配置

4. **JWT 验证失败**
   - 检查 JWT 密钥是否正确
   - 检查 JWT 令牌是否过期

### 7.2 调试方法

1. **查看日志**：查看 `logs/server.log` 文件，了解系统运行状态和错误信息。

2. **使用 API 文档**：访问 `http://localhost:3001/api/api-docs`，测试 API 接口。

3. **使用健康检查**：访问 `http://localhost:3001/api/v1/monitoring/health`，检查系统健康状态。

4. **使用 Ping 测试**：访问 `http://localhost:3001/api/v1/monitoring/ping`，测试系统响应。

## 8. 升级与维护

### 8.1 升级步骤

1. 停止服务：
   ```bash
   sudo systemctl stop serverjava
   ```

2. 备份数据：
   ```bash
   mysqldump -u root -p crawlful_hub > crawlful_hub_backup.sql
   ```

3. 拉取最新代码：
   ```bash
   git pull
   ```

4. 重新构建项目：
   ```bash
   mvn clean package
   ```

5. 启动服务：
   ```bash
   sudo systemctl start serverjava
   ```

### 8.2 维护计划

1. **定期备份**：定期备份数据库和配置文件。

2. **更新依赖**：定期更新项目依赖，确保系统安全。

3. **监控系统**：使用监控工具监控系统运行状态，及时发现和处理异常。

4. **性能优化**：根据系统运行情况，优化数据库查询、缓存策略等。

## 9. 总结

本部署指南详细介绍了 Crawlful Hub 项目的部署方法、环境要求和配置步骤。通过本指南，您可以快速部署和维护系统，确保系统的稳定运行。