# 快速部署指南

> 首次将 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` | 查看证书到期时间 |