# 测试服务器部署指南

## 1. 测试服务器环境准备

### 1.1 操作系统要求

- Linux 系统（推荐 Ubuntu 20.04 LTS 或 CentOS 7+）
- 至少 2GB 内存
- 至少 20GB 磁盘空间
- 网络连接正常

### 1.2 系统更新

```bash
# Ubuntu/Debian
apt update && apt upgrade -y

# CentOS/RHEL
yum update -y
```

## 2. 依赖服务安装

### 2.1 Java 17 安装

```bash
# Ubuntu/Debian
apt install openjdk-17-jdk -y

# CentOS/RHEL
yum install java-17-openjdk -y

# 验证安装
java -version
```

### 2.2 MySQL 8.0 安装

```bash
# Ubuntu/Debian
apt install mysql-server -y

# CentOS/RHEL
yum install mysql-server -y

# 启动并设置开机自启
systemctl start mysql
systemctl enable mysql

# 安全配置（设置密码等）
# Ubuntu/Debian
mysql_secure_installation
# CentOS/RHEL
sudo mysql_secure_installation
```

### 2.3 Redis 7.x 安装

```bash
# Ubuntu/Debian
apt install redis-server -y

# CentOS/RHEL
yum install redis -y

# 启动并设置开机自启
systemctl start redis
systemctl enable redis
```

### 2.4 RabbitMQ 安装（可选）

```bash
# Ubuntu/Debian
apt install rabbitmq-server -y

# CentOS/RHEL
yum install rabbitmq-server -y

# 启动并设置开机自启
systemctl start rabbitmq-server
systemctl enable rabbitmq-server

# 启用管理界面（可选）
rabbitmq-plugins enable rabbitmq_management
```

### 2.5 Maven 安装

```bash
# Ubuntu/Debian
apt install maven -y

# CentOS/RHEL
yum install maven -y

# 验证安装
mvn --version
```

## 3. 项目代码部署

### 3.1 克隆代码

```bash
# 选择部署目录
cd /opt

# 克隆代码（假设使用 Git）
git clone <项目仓库地址> openclaw

# 进入项目目录
cd openclaw
```

### 3.2 数据库初始化

```bash
# 登录 MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE openclaw DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 退出 MySQL
exit

# 执行初始化脚本
mysql -u root -p openclaw < openclaw-backend/openclaw-backend/src/main/resources/db/init.sql
```

### 3.3 配置修改

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

```yaml
# 数据库配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/openclaw?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: your_mysql_password
    driver-class-name: com.mysql.cj.jdbc.Driver

# Redis 配置
  data:
    redis:
      host: localhost
      port: 6379
      database: 0

# JWT 密钥（测试环境也建议修改）
jwt:
  secret: your_jwt_secret_key
  expire-ms: 86400000

# 服务端口（可选修改）
server:
  port: 8080

# 微信支付配置（测试环境可保持关闭）
wechat:
  pay:
    enabled: false

# 腾讯云短信配置（测试环境可保持关闭）
tencent:
  sms:
    enabled: false
```

## 4. 项目构建

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

# 构建项目
mvn clean package -DskipTests

# 查看构建结果
ls -la target/
```

## 5. 服务启动

### 5.1 方式一：直接运行（开发测试）

```bash
# 运行项目
java -jar target/openclaw-backend-1.0.0.jar
```

### 5.2 方式二：使用 systemd 管理（推荐）

创建 systemd 服务文件：

```bash
vi /etc/systemd/system/openclaw-backend.service
```

添加以下内容：

```ini
[Unit]
Description=OpenClaw Backend Service
After=network.target mysql.service redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/openclaw/openclaw-backend/openclaw-backend
ExecStart=/usr/bin/java -jar target/openclaw-backend-1.0.0.jar
Restart=on-failure
RestartSec=5s

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

启动服务：

```bash
# 重新加载 systemd 配置
systemctl daemon-reload

# 启动服务
systemctl start openclaw-backend

# 设置开机自启
systemctl enable openclaw-backend

# 查看服务状态
systemctl status openclaw-backend
```

## 6. 服务验证

### 6.1 健康检查

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

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

### 6.2 访问 Swagger 文档

在浏览器中访问：
```
http://<服务器IP>:8080/swagger-ui.html
```

### 6.3 查看服务日志

```bash
# 查看 systemd 服务日志
journalctl -u openclaw-backend -f

# 或查看应用日志（如果配置了日志文件）
tail -f /path/to/logs/openclaw-backend.log
```

## 7. 前端部署（可选）

### 7.1 安装 Node.js

```bash
# Ubuntu/Debian
apt install nodejs npm -y

# CentOS/RHEL
yum install nodejs npm -y

# 验证安装
node -v
npm -v
```

### 7.2 构建前端项目

```bash
# 进入前端目录
cd /opt/openclaw/frontend

# 安装依赖
npm install

# 构建项目
npm run build

# 查看构建结果
ls -la dist/
```

### 7.3 部署前端静态文件

使用 Nginx 或 Apache 部署前端静态文件：

```bash
# 安装 Nginx
apt install nginx -y  # Ubuntu/Debian
yum install nginx -y  # CentOS/RHEL

# 配置 Nginx
vi /etc/nginx/sites-available/openclaw
```

添加以下内容：

```nginx
server {
    listen 80;
    server_name <服务器IP或域名>;

    root /opt/openclaw/frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 反向代理后端 API
    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

启用配置：

```bash
# Ubuntu/Debian
ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/

# 测试配置
nginx -t

# 重启 Nginx
systemctl restart nginx
```

## 8. 监控与维护

### 8.1 查看服务状态

```bash
# 查看后端服务状态
systemctl status openclaw-backend

# 查看 MySQL 状态
systemctl status mysql

# 查看 Redis 状态
systemctl status redis

# 查看 Nginx 状态（如果部署了前端）
systemctl status nginx
```

### 8.2 日志管理

```bash
# 查看后端服务日志
journalctl -u openclaw-backend --since "2 days ago"

# 查看 MySQL 日志
journalctl -u mysql

# 查看 Nginx 日志
cat /var/log/nginx/access.log
cat /var/log/nginx/error.log
```

### 8.3 服务重启

```bash
# 重启后端服务
systemctl restart openclaw-backend

# 重启 MySQL
systemctl restart mysql

# 重启 Redis
systemctl restart redis

# 重启 Nginx
systemctl restart nginx
```

## 9. 常见问题排查

### 9.1 数据库连接失败

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

### 9.2 Redis 连接失败

- 检查 Redis 服务是否运行
- 检查 Redis 配置是否正确
- 检查防火墙是否允许 Redis 端口

### 9.3 端口占用

- 检查端口是否被占用：
  ```bash
  netstat -tlnp | grep 8080
  ```
- 如果端口被占用，修改 `application.yml` 中的端口配置

### 9.4 依赖服务未启动

- 确保所有依赖服务都已启动：
  ```bash
  systemctl status mysql redis rabbitmq-server
  ```

### 9.5 内存不足

- 检查服务器内存使用情况：
  ```bash
  free -h
  ```
- 如内存不足，考虑增加服务器内存或优化应用配置

## 10. 部署验证

部署完成后，建议进行以下验证：

1. **后端服务**：访问健康检查端点和 Swagger 文档
2. **数据库连接**：检查数据库连接池状态
3. **API 测试**：使用 Postman 或 Swagger 测试核心 API
4. **前端访问**：如果部署了前端，访问前端页面验证功能

## 11. 安全建议

1. **修改默认密码**：修改 MySQL、Redis 等服务的默认密码
2. **配置防火墙**：只开放必要的端口
3. **使用 HTTPS**：在生产环境中配置 HTTPS
4. **定期备份**：定期备份数据库和关键配置
5. **监控设置**：设置服务器和应用监控

---

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