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

# 方式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

# 下载并安装 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 克隆代码

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

2.4 配置环境变量

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

2.5 启动服务

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

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

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

2.6 数据库迁移

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

# 执行迁移
make migrate

# 填充初始数据
make seed

2.7 构建服务端

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 中添加：

[[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 中添加：

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";
    }
}

---

四、常用命令

# 启动服务
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 无法启动

# 从 Windows 侧启动
wsl -d Ubuntu

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

Docker 服务启动失败

# 检查 Docker 状态
docker info

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

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

数据库连接失败

# 检查 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 | 初始版本