number/后端启动指南.md

# 后端启动指南

## 项目简介

OpenClaw 后端系统是一个基于 Spring Boot 3.2 + MyBatis Plus 的技能交易平台后端，采用模块化单体架构。

## 技术栈

| 组件 | 技术 |
|------|------|
| 框架 | Java 17 + Spring Boot 3.2 + MyBatis Plus 3.5 |
| 数据 | MySQL 8.0 + Redis 7.x |
| 消息 | RabbitMQ（可选，有降级同步处理） |
| 支付 | 微信支付 SDK + 支付宝 SDK |
| 短信 | 腾讯云 SMS SDK |
| ID | Leaf Segment 号段模式 |
| 文档 | OpenAPI/Swagger |
| 安全 | JWT + Spring Security + RBAC |

## 环境要求

- Java 17 或更高版本
- MySQL 8.0 或更高版本
- Redis 7.x 或更高版本
- Maven 3.6 或更高版本
- RabbitMQ（可选）

## 启动步骤

### 1. 检查环境

#### 检查 Java 版本

```bash
java -version
```

#### 检查 Maven 版本

```bash
mvn --version
```

#### 检查 MySQL 服务状态

```bash
# Windows
sc query mysql

# Linux
systemctl status mysql
```

#### 检查 Redis 服务状态

```bash
# Windows
sc query redis

# Linux
systemctl status redis
```

### 2. 数据库初始化

#### 执行初始化脚本

```bash
# Windows (PowerShell)
Get-Content "src\main\resources\db\init.sql" | mysql -u root -p

# Linux/macOS
mysql -u root -p < src/main/resources/db/init.sql
```

**注意**：如果数据库已存在，脚本会自动跳过创建步骤，只创建缺失的表。

### 3. 配置修改（可选）

#### 数据库配置

编辑 `src/main/resources/application.yml` 文件：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/openclaw?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: 177615  # 修改为你的 MySQL 密码
    driver-class-name: com.mysql.cj.jdbc.Driver
```

#### Redis 配置

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 0
      timeout: 3000ms
```

#### JWT 密钥（生产环境必须修改）

```yaml
jwt:
  secret: change-this-to-a-256-bit-random-secret-key-for-production
  expire-ms: 86400000
```

### 4. 启动服务

#### 方式一：使用 Maven 直接启动

```bash
# 进入后端项目目录
cd openclaw-backend\openclaw-backend

# 启动服务
mvn spring-boot:run
```

#### 方式二：编译后运行

```bash
# 进入后端项目目录
cd openclaw-backend\openclaw-backend

# 编译项目
mvn clean package -DskipTests

# 运行编译后的 jar 文件
java -jar target/openclaw-backend-1.0.0.jar
```

### 5. 验证服务

服务启动成功后，可以通过以下方式验证：

#### 1. 访问健康检查端点

```bash
curl http://localhost:8080/actuator/health
```

预期响应：
```json
{"status":"UP"}
```

#### 2. 访问 Swagger 文档

打开浏览器访问：
```
http://localhost:8080/swagger-ui.html
```

#### 3. 检查服务日志

服务启动成功的日志示例：

```
2026-03-20T09:50:06.640+08:00  INFO 8544 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path ''
2026-03-20T09:50:06.882+08:00  INFO 8544 --- [           main] com.openclaw.OpenclawApplication         : Started OpenclawApplication in 6.943 seconds (process running for 7.429)
```

## 常见问题

### 1. 数据库连接失败

- 检查 MySQL 服务是否运行
- 检查数据库用户名和密码是否正确
- 检查数据库 `openclaw` 是否已创建

### 2. Redis 连接失败

- 检查 Redis 服务是否运行
- 检查 Redis 配置是否正确

### 3. 端口占用

- 默认端口为 8080，如果被占用，可以修改 `application.yml` 中的端口配置：

```yaml
server:
  port: 8081  # 修改为其他端口
```

### 4. Maven 依赖下载失败

- 检查网络连接
- 清理 Maven 缓存：

```bash
mvn dependency:purge-local-repository
```

## 生产环境部署建议

1. **修改 JWT 密钥**：使用强随机密钥
2. **配置 HTTPS**：确保生产环境使用 HTTPS
3. **关闭 Swagger**：在生产环境中设置 `SWAGGER_ENABLED=false`
4. **配置监控**：设置适当的监控和日志系统
5. **备份策略**：定期备份数据库

## 服务状态管理

### 停止服务

- 在运行 Maven 命令的终端中按 `Ctrl+C`
- 或查找进程并终止：

```bash
# Windows
taskkill /F /PID <进程ID>

# Linux
kill <进程ID>
```

### 查看服务日志

- Maven 启动方式：直接查看终端输出
- Jar 运行方式：查看控制台输出或配置日志文件

## 相关文件

- **数据库初始化脚本**：`src/main/resources/db/init.sql`
- **配置文件**：`src/main/resources/application.yml`
- **启动类**：`src/main/java/com/openclaw/OpenclawApplication.java`

## 联系方式

如果在启动过程中遇到问题，请联系技术支持。

---

**最后更新**：2026-03-20