docs: 拆分 README.md 为多个子文档，README 简化为架构引导大纲
This commit is contained in:
249
codes/agent/game-docker/docs/01-deployment.md
Normal file
249
codes/agent/game-docker/docs/01-deployment.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 快速部署指南
|
||||
|
||||
> 首次将 YouleGames Docker 版部署到服务器的完整步骤。
|
||||
|
||||
---
|
||||
|
||||
## 前置要求
|
||||
|
||||
- Linux 服务器（推荐 Ubuntu 22.04 / CentOS 8+，最低 2C 2G）
|
||||
- 域名已解析到服务器 IP（3 个域名：API / DLWEB / wxserver）
|
||||
- 服务器 80 和 443 端口可用
|
||||
- Docker 和 Docker Compose（如未安装，`deploy.sh` 会自动安装并配置国内镜像加速）
|
||||
|
||||
---
|
||||
|
||||
## 步骤 0：配置 SSH 密钥认证（必须）
|
||||
|
||||
`sync.ps1` 每次执行会调用多次 `scp` / `ssh`，如果未配置密钥认证，每条命令都会弹出密码提示导致脚本中断。以下步骤在 **Windows PowerShell** 中完成（Windows 10/11 内置 OpenSSH 客户端，无需额外安装）。
|
||||
|
||||
### 第一步：检查是否已有 SSH 密钥
|
||||
|
||||
```powershell
|
||||
# 默认密钥路径
|
||||
Test-Path "$env:USERPROFILE\.ssh\id_ed25519"
|
||||
# 输出 True 表示已有密钥，可跳到第三步
|
||||
```
|
||||
|
||||
如果已有 RSA 旧密钥（`id_rsa`），同样可用，把下面命令中的 `id_ed25519` 替换为 `id_rsa`。
|
||||
|
||||
### 第二步：生成密钥对
|
||||
|
||||
```powershell
|
||||
# 生成 Ed25519 密钥（更安全、更短）
|
||||
ssh-keygen -t ed25519 -C "youle-deploy" -f "$env:USERPROFILE\.ssh\id_ed25519"
|
||||
# 提示 passphrase 时直接回车两次（不设密码，脚本才能自动运行）
|
||||
```
|
||||
|
||||
执行后生成两个文件：
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `~/.ssh/id_ed25519` | **私钥**，绝不上传服务器，本地保管 |
|
||||
| `~/.ssh/id_ed25519.pub` | **公钥**，要发给服务器 |
|
||||
|
||||
### 第三步：将公钥上传到服务器
|
||||
|
||||
> 此步骤会要求输入一次密码，之后不再需要。
|
||||
|
||||
```powershell
|
||||
# 一行命令：读取公钥 → 追加到服务器 authorized_keys
|
||||
cat "$env:USERPROFILE\.ssh\id_ed25519.pub" | ssh root@47.98.203.17 `
|
||||
"mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"
|
||||
```
|
||||
|
||||
### 第四步：验证免密登录
|
||||
|
||||
```powershell
|
||||
# 直接登录，不弹密码提示则成功
|
||||
ssh root@47.98.203.17 "echo 'SSH key auth OK'"
|
||||
```
|
||||
|
||||
输出 `SSH key auth OK` 即表示配置成功，`sync.ps1` 可正常使用。
|
||||
|
||||
### 可选：配置 SSH 别名（简化命令）
|
||||
|
||||
在 `C:\Users\<你的用户名>\.ssh\config`（文件不存在则新建）中添加：
|
||||
|
||||
```
|
||||
Host youle
|
||||
HostName 47.98.203.17
|
||||
User root
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
ServerAliveInterval 60
|
||||
```
|
||||
|
||||
配置后可使用短名称操作：
|
||||
|
||||
```powershell
|
||||
ssh youle # 直接登录
|
||||
# sync.ps1 使用别名
|
||||
.\sync.ps1 -Server youle
|
||||
```
|
||||
|
||||
### 可选：多台电脑共用同一台服务器
|
||||
|
||||
把每台电脑生成的 `id_ed25519.pub` 内容都追加到服务器的 `~/.ssh/authorized_keys`（一行一个），不需要删除旧的公钥：
|
||||
|
||||
```powershell
|
||||
# 在第二台电脑上执行同样的上传命令即可（>> 追加而不是覆盖）
|
||||
cat "$env:USERPROFILE\.ssh\id_ed25519.pub" | ssh root@47.98.203.17 `
|
||||
"cat >> ~/.ssh/authorized_keys"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 1：检查并修复行尾符（LF）
|
||||
|
||||
> **为什么需要这步？** Windows 的 Git 默认 `core.autocrlf=true`，可能将脚本文件写成 CRLF。CRLF 格式的 shell 脚本在 Linux 容器中会报 `not found` / `syntax error` 错误，导致容器无法启动。
|
||||
|
||||
在上传前运行 `fix-lf.ps1`，自动扫描所有关键文件并修复：
|
||||
|
||||
```powershell
|
||||
.\fix-lf.ps1
|
||||
```
|
||||
|
||||
> **根本修复（一次性，之后无需再跑）：** 执行以下命令让 `.gitattributes` 永久接管行尾符，此后任何机器 clone 均自动生效：
|
||||
> ```powershell
|
||||
> git config core.autocrlf false
|
||||
> git add --renormalize .
|
||||
> git commit -m "fix: normalize all line endings to LF"
|
||||
> git push
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 2：上传项目到服务器
|
||||
|
||||
将 `game-docker` 目录上传到服务器 `/opt/youle/` 下：
|
||||
|
||||
```powershell
|
||||
# 推荐：使用 sync.ps1（tar 压缩单连接，比 scp -r 快约 10-50 倍）
|
||||
# 首次部署用 full 模式，上传全部文件（约 10 MB 压缩包）
|
||||
.\sync.ps1 -Mode full
|
||||
|
||||
# 日常代码更新用 app 模式（排除文档/测试，约 7 MB）
|
||||
.\sync.ps1
|
||||
|
||||
# 仅更新 Docker 配置文件（docker-compose.yml、deploy.sh 等，不到 1 MB）
|
||||
.\sync.ps1 -Mode config
|
||||
```
|
||||
|
||||
> **前提：** 已完成步骤 0 的 SSH 密钥认证配置，否则 `sync.ps1` 会反复弹密码提示。
|
||||
|
||||
`sync.ps1` 会自动在服务器上创建 `/opt/youle/game-docker/` 目录（如不存在）。
|
||||
|
||||
如不使用 `sync.ps1`，也可手动上传：
|
||||
|
||||
```bash
|
||||
# 从 Git 仓库拉取
|
||||
ssh root@your-server-ip
|
||||
mkdir -p /opt/youle
|
||||
cd /opt/youle
|
||||
git clone <仓库地址> game-docker
|
||||
```
|
||||
|
||||
上传后服务器上的目录结构：
|
||||
|
||||
```
|
||||
/opt/youle/game-docker/
|
||||
├── .env.example
|
||||
├── docker-compose.yml
|
||||
├── deploy.sh
|
||||
├── init-ssl.sh
|
||||
├── api/
|
||||
├── dlweb/
|
||||
├── wxserver_daoqi/
|
||||
└── docker/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 3：准备环境变量
|
||||
|
||||
```bash
|
||||
cd /opt/youle/game-docker
|
||||
cp .env.example .env
|
||||
vim .env
|
||||
```
|
||||
|
||||
**必须修改的关键配置：**
|
||||
|
||||
```bash
|
||||
# 父域名（三个子域名自动推导，无需单独配置）
|
||||
# 将自动生成: api.<ROOT_DOMAIN> dlapi.<ROOT_DOMAIN>
|
||||
ROOT_DOMAIN=yourdomain.com
|
||||
|
||||
# 数据库（各服务数据库连接）
|
||||
API_DB_HOST=your-rds-host
|
||||
API_DB_PASSWORD=your-password
|
||||
DLWEB_DB_HOST=your-rds-host
|
||||
DLWEB_DB_PASSWORD=your-password
|
||||
# ... 其他数据库配置
|
||||
|
||||
# 微信配置
|
||||
WX_MINI_APPID=your-appid
|
||||
WX_MINI_APPSECRET=your-secret
|
||||
WX_PAY_MCHID=your-mchid
|
||||
WX_PAY_KEY=your-key
|
||||
|
||||
# SSL 邮箱
|
||||
SSL_EMAIL=your-email@example.com
|
||||
```
|
||||
|
||||
> 完整变量说明见 [环境变量配置](./03-env-variables.md)。
|
||||
|
||||
---
|
||||
|
||||
## 步骤 4：首次申请 SSL 证书
|
||||
|
||||
```bash
|
||||
chmod +x deploy.sh init-ssl.sh
|
||||
|
||||
# 先测试（不真正申请，验证域名解析是否正确）
|
||||
./deploy.sh ssl-init --dry-run
|
||||
|
||||
# 正式申请
|
||||
./deploy.sh ssl-init
|
||||
```
|
||||
|
||||
> SSL 证书详细管理见 [SSL 证书管理](./04-ssl.md)。
|
||||
|
||||
---
|
||||
|
||||
## 步骤 5：启动所有服务
|
||||
|
||||
```bash
|
||||
./deploy.sh up
|
||||
```
|
||||
|
||||
启动后验证：
|
||||
|
||||
```bash
|
||||
# 查看所有容器状态
|
||||
./deploy.sh status
|
||||
|
||||
# 查看特定服务日志
|
||||
./deploy.sh logs api
|
||||
./deploy.sh logs dlweb
|
||||
./deploy.sh logs syncjob
|
||||
./deploy.sh logs cronjob
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 6：部署命令速查
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `./deploy.sh up` | 构建并启动所有服务 |
|
||||
| `./deploy.sh down` | 停止并移除所有容器 |
|
||||
| `./deploy.sh restart` | 重启所有服务 |
|
||||
| `./deploy.sh rebuild` | 无缓存重建所有镜像 |
|
||||
| `./deploy.sh rebuild api` | 只重建指定服务 |
|
||||
| `./deploy.sh logs [service]` | 查看日志（支持 `-f` 实时跟踪） |
|
||||
| `./deploy.sh status` | 查看容器运行状态 |
|
||||
| `./deploy.sh ssl-init` | 首次申请 SSL 证书 |
|
||||
| `./deploy.sh ssl-init --staging` | 用 Let's Encrypt 测试环境申请 |
|
||||
| `./deploy.sh ssl-renew` | 手动续签证书 |
|
||||
| `./deploy.sh ssl-status` | 查看证书到期时间 |
|
||||
Reference in New Issue
Block a user