# 部署指南

## 架构概览

```
Internet → Gateway Nginx (80/443)
  ├─ rent-prod 网络
  │   ├─ rent-prod-mysql (3306)
  │   ├─ rent-prod-redis (6379)
  │   ├─ rent-prod-server (3000)
  │   ├─ rent-prod-merchant (8081→80)
  │   ├─ rent-prod-platform (8082→80)
  │   └─ rent-prod-website (8083→80)
  └─ rent-test 网络
      ├─ rent-test-mysql (3307→3306)
      ├─ rent-test-redis (6380→6379)
      ├─ rent-test-server (3001→3000)
      ├─ rent-test-merchant (9081→80)
      ├─ rent-test-platform (9082→80)
      └─ rent-test-website (9083→80)
```

## 域名规划

| 环境 | 用途 | 域名 |
|------|------|------|
| 生产 | API | api.pinzhuhui.com |
| 生产 | 官网 | www.pinzhuhui.com |
| 生产 | 商家后台 | merchant.pinzhuhui.com |
| 生产 | 平台后台 | platform-admin.pinzhuhui.com |
| 测试 | API | api-test.pinzhuhui.com |
| 测试 | 官网 | test.pinzhuhui.com |
| 测试 | 商家后台 | merchant-test.pinzhuhui.com |
| 测试 | 平台后台 | platform-admin-test.pinzhuhui.com |

## 目录结构

```text
deploy/
├── docker/
│   ├── docker-compose.prod.yml      # 生产环境
│   ├── docker-compose.test.yml      # 测试环境
│   ├── docker-compose.gateway.yml   # Gateway 网关
│   ├── Dockerfile.server            # 后端镜像
│   ├── Dockerfile.merchant          # 商家后台镜像
│   ├── Dockerfile.platform          # 平台后台镜像
│   ├── Dockerfile.website           # 官网镜像
│   ├── .env.example                 # 环境变量模板
│   └── .env                         # 实际配置（不入仓库）
├── nginx/
│   ├── gateway/gateway.conf         # Gateway 域名路由
│   ├── api.conf                     # 后端 Nginx 配置
│   ├── merchant.conf                # 商家后台 Nginx 配置
│   └── platform.conf                # 平台后台 Nginx 配置
scripts/
│   └── setup-server.sh              # 首次初始化脚本
```

---

## 一、首次部署（服务器初始化）

### 第 1 步：运行初始化脚本

```bash
# 将代码克隆到服务器
git clone <你的Gitea仓库地址> ~/rent-platform
cd ~/rent-platform

# 运行初始化（安装 Docker、创建网络、启动 Gitea + 网关）
bash scripts/setup-server.sh
```

脚本会自动完成：
- 安装 Docker、Docker Compose、Git、pnpm
- 启动 Gitea + Act Runner
- 创建 Docker 网络（rent-prod、rent-test）
- 启动 Gateway Nginx

### 第 2 步：配置 DNS

在你的域名管理面板添加 A 记录，将以下域名指向服务器 IP：

```text
# 生产环境
api.pinzhuhui.com            → 服务器IP
www.pinzhuhui.com            → 服务器IP
merchant.pinzhuhui.com       → 服务器IP
platform-admin.pinzhuhui.com → 服务器IP

# 测试环境
api-test.pinzhuhui.com            → 服务器IP
test.pinzhuhui.com                → 服务器IP
merchant-test.pinzhuhui.com       → 服务器IP
platform-admin-test.pinzhuhui.com → 服务器IP
```

### 第 3 步：部署服务

```bash
# 部署生产环境
make prod-deploy

# 部署测试环境
make test-deploy
```

---

## 二、Gitea + Act Runner 自动化

> Gitea 内存占用约 100MB，适合 4GB 小内存服务器。

### 前提条件

- 服务器已运行初始化脚本（Gitea 和 Act Runner 已自动启动）
- Gitea 已完成初始配置

### 第 1 步：配置 Gitea

首次初始化已自动启动 Gitea，访问 `http://服务器IP:3002` 完成：

1. 设置管理员账号密码
2. 创建仓库 `rent-platform`

### 第 2 步：注册 Act Runner

1. Gitea → **Settings → Actions → Runners → Create new Runner**
2. 复制 Registration Token
3. 编辑 `.env` 填入 token：

```bash
vi deploy/docker/.env
# 将 GITEA_RUNNER_TOKEN=change_me 改为真实 token
```

4. 重启 Runner：

```bash
docker compose -f deploy/docker/docker-compose.gitea.yml restart act-runner
```

5. 验证 Runner 状态：

```bash
docker logs rent-act-runner
```

在 Gitea → **Settings → Actions → Runners** 页面应能看到 `rent-deploy-runner` 已注册并在线。

### 第 3 步：配置 Secrets

> CI/CD 流水线只需要 4 个基础密钥，其他业务密钥（微信、支付宝、短信等）通过平台后台「系统密钥」页面管理。

Gitea → **仓库 → Settings → Actions → Secrets**，添加：

| Secret 名 | 说明 | 生成方式 |
|-----------|------|----------|
| `PROD_DB_PASSWORD` | 生产数据库密码 | 自定义强密码 |
| `PROD_JWT_SECRET` | 生产 JWT 密钥 | `openssl rand -hex 32` |
| `TEST_DB_PASSWORD` | 测试数据库密码 | 自定义强密码 |
| `TEST_JWT_SECRET` | 测试 JWT 密钥 | `openssl rand -hex 32` |
| `ENCRYPTION_KEY` | 业务密钥加密密钥 | `openssl rand -hex 32` |

> `ENCRYPTION_KEY` 用于加解密数据库中存储的业务密钥（微信、支付宝等），务必妥善保管。

业务密钥（微信、支付宝、短信等）的配置方式：平台后台 → **系统密钥** 页面。

### 第 4 步：推送代码到 Gitea

```bash
# 添加 Gitea 远程仓库
git remote add gitea http://服务器IP:3002/用户名/rent-platform.git

# 推送分支
git push gitea master
git push gitea test
git push gitea prod
```

### 第 5 步：自动部署触发

```bash
# 推送 test 分支 → 自动部署测试环境
git push gitea test

# 推送 prod 分支 → 自动部署生产环境
git push gitea prod
```

流水线：install → build → generate .env from secrets → deploy

在 Gitea → **仓库 → Actions** 页面查看实时日志。

---

## 三、常用命令

```bash
make help              # 查看所有命令

# 生产环境
make prod-deploy       # 完整部署（停止→构建→启动）
make prod-logs         # 查看日志
make prod-logs-server  # 查看后端日志
make prod-ps           # 查看容器状态
make prod-restart      # 重启

# 测试环境
make test-deploy       # 完整部署
make test-logs         # 查看日志
make test-ps           # 查看容器状态
make test-restart      # 重启

# 网关
make gateway-up        # 启动网关
make gateway-reload    # 重载网关配置

# 其他
make clean             # 清理所有环境（包括数据）
```

---

## 四、故障排查

### 查看服务状态

```bash
make prod-ps    # 生产环境
make test-ps    # 测试环境
```

### 查看日志

```bash
make prod-logs          # 生产环境所有日志
make prod-logs-server   # 生产环境后端日志
make test-logs          # 测试环境所有日志

# 直接查看某个容器
docker logs rent-prod-server
docker logs rent-test-mysql
```

### 数据库连接

```bash
# 生产环境
docker exec -it rent-prod-mysql mysql -u root -p rent_platform

# 测试环境
docker exec -it rent-test-mysql mysql -u root -p rent_platform
```

### 重建单个服务

```bash
# 只重建生产环境后端
docker-compose -f deploy/docker/docker-compose.prod.yml up -d --build server

# 只重建测试环境商家后台
docker-compose -f deploy/docker/docker-compose.test.yml up -d --build merchant-admin
```

### 网关问题

```bash
# 检查网关状态
docker logs rent-gateway

# 重载网关配置（修改了 gateway.conf 后）
make gateway-reload
```