lawless/docs/部署指南.md

# 洪荒大陆 - WSL 部署指南

> 目标环境：win.xuqinmin.com (Windows 10 WSL2 Ubuntu)
> 最后更新：2026-07-03

---

## 一、环境要求

| 组件 | 最低要求 | 当前环境 |
|------|---------|---------|
| 内存 | 4GB 可用 | 23GB 可用 ✅ |
| 磁盘 | 20GB 可用 | 943GB 可用 ✅ |
| Docker | 20.x+ | v29.5.3 ✅ |
| Docker Compose | 2.x+ | v5.1.4 ✅ |
| Git | 2.x+ | v2.43.0 ✅ |
| Go | 1.22+ | ❌ 需安装 |

---

## 二、部署步骤

### 2.1 连接 WSL

```bash
# 方式1：通过 Jenkins SSH 连接 Windows，再进入 WSL
ssh -i ~/.ssh/id_rsa -p 2222 xuqm@jenkins.xuqinmin.com
wsl -d Ubuntu

# 方式2：直接连接 WSL SSH（需先启动 WSL）
ssh -i ~/.ssh/id_ed25519 -p 2224 xuqm@win.xuqinmin.com
```

### 2.2 安装 Go

```bash
# 下载并安装 Go 1.22
wget -q https://go.dev/dl/go1.22.4.linux-amd64.tar.gz -O /tmp/go.tar.gz
sudo tar -C /usr/local -xzf /tmp/go.tar.gz
rm /tmp/go.tar.gz

# 添加到 PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# 验证
go version
```

### 2.3 克隆代码

```bash
cd ~
git clone https://xuqinmin.com/<组织>/lawless.git
cd lawless
```

### 2.4 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，确认以下配置：
# - DATABASE_URL: postgres://postgres:postgres@localhost:5432/honghuang?sslmode=disable
# - REDIS_URL: redis://localhost:6379
```

### 2.5 启动服务

```bash
# 使用独立项目名，避免与其他服务冲突
docker compose -p lawless up -d

# 查看服务状态
docker compose -p lawless ps

# 查看日志
docker compose -p lawless logs -f
```

### 2.6 数据库迁移

```bash
# 等待 PostgreSQL 就绪
docker compose -p lawless exec postgres pg_isready -U postgres

# 执行迁移
make migrate

# 填充初始数据
make seed
```

### 2.7 构建服务端

```bash
cd server
make build
# 生成 honghuang-server.so，Nakama 会自动加载
```

---

## 三、服务访问

### 本地访问

| 服务 | 地址 | 用途 |
|------|------|------|
| PostgreSQL | localhost:5432 | 数据库 |
| Valkey | localhost:6379 | 缓存 |
| Nakama gRPC | localhost:7349 | 游戏客户端连接 |
| Nakama HTTP | localhost:7350 | REST API |
| Nakama Console | localhost:7351 | 管理后台 |
| Nacos | localhost:8848 | 配置中心 |

### 外网访问

如需外网访问，可通过以下方式：

**方式1：frp 隧道**

在 Windows 的 `C:\frp\frpc.toml` 中添加：

```toml
[[proxies]]
name = "lawless-nakama"
type = "tcp"
localIP = "172.24.243.38"
localPort = 7350
remotePort = 10750

[[proxies]]
name = "lawless-console"
type = "tcp"
localIP = "172.24.243.38"
localPort = 7351
remotePort = 10751
```

**方式2：nginx 反代**

在云服务器 nginx 中添加：

```nginx
server {
    listen 443 ssl;
    server_name game.xuqinmin.com;

    location / {
        proxy_pass http://127.0.0.1:10750;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /ws {
        proxy_pass http://127.0.0.1:10750;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

---

## 四、常用命令

```bash
# 启动服务
docker compose -p lawless up -d

# 停止服务
docker compose -p lawless down

# 重启服务
docker compose -p lawless restart

# 查看日志
docker compose -p lawless logs -f [服务名]

# 进入容器
docker compose -p lawless exec postgres psql -U postgres

# 重新构建
docker compose -p lawless up -d --build

# 清理数据（谨慎！）
docker compose -p lawless down -v
```

---

## 五、端口规划

| 端口 | 服务 | 说明 |
|------|------|------|
| 5432 | PostgreSQL | 数据库 |
| 6379 | Valkey | 缓存（现有服务用 16379，无冲突） |
| 7349 | Nakama gRPC | 游戏客户端连接 |
| 7350 | Nakama HTTP | REST API |
| 7351 | Nakama Console | 管理后台 |
| 8848 | Nacos | 配置中心 |

---

## 六、注意事项

1. **项目名隔离**：使用 `-p lawless` 参数，避免与现有 `xuqm-private` 项目冲突
2. **内存限制**：Nacos + PostgreSQL + Nakama + Valkey 约需 2-3GB 内存
3. **数据持久化**：Docker volumes 存储在 WSL 内部，WSL 重启不影响数据
4. **WSL 生命周期**：WSL 默认会在无活动后自动关闭，可通过 `.wslconfig` 配置
5. **防火墙**：如需外网访问，确保 Windows 防火墙允许 WSL 网段访问对应端口

---

## 七、故障排查

### WSL 无法启动

```bash
# 从 Windows 侧启动
wsl -d Ubuntu

# 如果 WSL 已停止，从 Windows 侧启动
wsl --list --verbose  # 检查状态
wsl -d Ubuntu -- echo "started"
```

### Docker 服务启动失败

```bash
# 检查 Docker 状态
docker info

# 检查端口占用
ss -tlnp | grep -E '5432|6379|7349|7350|7351|8848'

# 查看容器日志
docker compose -p lawless logs [服务名]
```

### 数据库连接失败

```bash
# 检查 PostgreSQL 是否就绪
docker compose -p lawless exec postgres pg_isready -U postgres

# 检查数据库是否存在
docker compose -p lawless exec postgres psql -U postgres -l
```

---

*部署指南 v1.0 | 2026-07-03 | 初始版本*