# PPanel 日本东京区 AWS 部署说明

本目录用于在 **AWS 日本东京区 `ap-northeast-1`** 重建一套全新生产环境，并承接当前香港区 `ap-east-1` 的正式迁移。

如果你要看“当前已经真实跑起来的东京架构”，优先看：

- [`ops/hifast-current-architecture-zh.md`](/Users/Apple/code_vpn/vpn/ppanel-server/ops/hifast-current-architecture-zh.md)
- [`configs/resource-inventory.current.md`](./configs/resource-inventory.current.md)

这份 README 更偏向：

- 目标架构
- 资源规划
- 部署方法
- 后续待完成项

目标架构：

`DNS -> ALB -> WAF -> EC2(Nginx + ppanel-server + Redis + observability) -> RDS MySQL`

灾备链路：

`RDS MySQL / EC2 Redis -> 104.238.220.230 外部灾备`

当前仓库内已补充：

- 东京基础设施参数模板：[`configs/aws-jp-infra.env.example`](./configs/aws-jp-infra.env.example)
- 东京真实实施状态登记：[`configs/resource-inventory.current.md`](./configs/resource-inventory.current.md)
- 东京底座资源创建脚本：[`../../scripts/aws_jp_create_base_infra.sh`](../../scripts/aws_jp_create_base_infra.sh)
- 东京资源状态检查脚本：[`../../scripts/aws_jp_describe_state.sh`](../../scripts/aws_jp_describe_state.sh)
- MySQL 备份脚本：[`../../scripts/mysql_backup_to_s3.sh`](../../scripts/mysql_backup_to_s3.sh)
- 10 分钟 MySQL 备份定时器安装脚本：[`../../scripts/install_mysql_backup_timer.sh`](../../scripts/install_mysql_backup_timer.sh)

## 1. 资源清单

按下面顺序创建资源：

1. VPC
2. 2 个公有子网 + 2 个私有子网
3. Internet Gateway
4. 公有 / 私有路由表
5. 安全组
6. RDS MySQL
7. EC2 本机 Redis Docker
8. EC2
9. ACM 证书
10. ALB + Target Group
11. WAF Web ACL
12. 东京平行环境域名
13. 东京 S3 备份桶

建议命名：

- VPC: `ppanel-jp-prod`
- EC2: `ppanel-app-jp-01`
- RDS: `ppanel-mysql-jp`
- Redis container: `hifast-redis`
- ALB: `ppanel-alb-jp`
- WAF: `ppanel-waf-jp`
- S3: `hifast-prod-backups-200810848252-ap-northeast-1`

## 2. 默认规格

### EC2

- Region: `ap-northeast-1`
- OS: Ubuntu 24.04 LTS
- Instance type: `t4g.large`
- Disk: `gp3 80GB`
- Public subnet: 是
- IAM Role:
  - 允许读取 CloudWatch / SSM（如使用）
  - 如果要在东京 EC2 上执行 S3 备份：额外允许写入东京备份桶

### RDS MySQL

- Engine: `MySQL 8.4`
- Class: `db.r7g.xlarge`
- Storage: `gp3 100GB`
- DB name: `hifast`
- Username: `admin`
- Public access: `Yes`
- Charset: `utf8mb4`
- Backup retention: `7-14 days`
- Deletion protection: `On`
- Multi-AZ: `Yes`（当前按 2 实例 Multi-AZ 创建）

说明：

- 当前东京 RDS 需要允许 `104.238.220.230` 从公网直连 `3306`，用于外部 MySQL 从库复制
- 因此本阶段 RDS 使用 `public subnet group + Publicly accessible = Yes`
- 访问面只通过 `sg-rds` 严格限制到业务 EC2 安全组和 `104.238.220.230/32`

### Redis

- 部署位置：业务 EC2 本机
- 部署方式：Docker
- 版本：`redis:8.2.1`
- 监听：`0.0.0.0:6379`
- 应用连接：`127.0.0.1:6379`
- 安全组：仅对白名单备用节点 `104.238.220.230/32` 或同机应用开放

## 3. 网络与安全组

### 子网布局

- `public-a`, `public-c`: ALB / EC2
- `private-a`, `private-c`: RDS

说明：

- 东京优先使用 `ap-northeast-1a` 和 `ap-northeast-1c`
- 如果账户映射不同，也可以用任意 2 个可用区，但公私网必须各 2 个子网

### 安全组建议

#### `sg-alb`

- Inbound
  - `80/tcp` from `0.0.0.0/0`
  - `443/tcp` from `0.0.0.0/0`
- Outbound
  - `80/tcp` to `sg-ec2`

#### `sg-ec2`

- Inbound
  - `80/tcp` from `sg-alb`
  - `22/tcp` from `你的固定运维 IP`
  - `6379/tcp` from `104.238.220.230/32`
- Outbound
  - all

说明：

- 应用容器监听 `127.0.0.1:8080`
- EC2 对外只让 Nginx 监听 `80`
- Grafana / Prometheus / Tempo 仅监听 `127.0.0.1`

#### `sg-rds`

- Inbound
  - `3306/tcp` from `sg-ec2`
  - `3306/tcp` from `104.238.220.230/32`

## 4. ALB / Target Group / 健康检查

### Target Group

- Type: `Instance`
- Protocol: `HTTP`
- Port: `80`
- Health check path: `/v1/common/heartbeat`
- Success code: `200`

### ALB 监听器

- `80` -> redirect to `443`
- `443` -> forward 到 target group

### ACM

- 在 `ap-northeast-1` 重新申请证书
- 先给平行环境域名，例如：
  - `api-jp.hifast.biz`
  - `logs-jp.hifast.biz`

## 5. WAF 规则

首版至少启用：

1. `AWSManagedRulesCommonRuleSet`
2. `AWSManagedRulesKnownBadInputsRuleSet`
3. `AWSManagedRulesAmazonIpReputationList`
4. 全站 rate-based rule
5. 针对高风险路径的 rate-based rule

建议的第一版限流：

- 全站：每 IP `2000 / 5 分钟`
- `/v1/public/user/subscribe`：每 IP `300 / 5 分钟`
- 登录 / 注册 / 验证码接口：每 IP `100 / 5 分钟`

节点上报接口建议后续补：

- `/v1/server/status`
- `/v1/server/online`
- `/v1/server/traffic`

## 6. EC2 文件落地

在 EC2 上建议使用：

- 应用目录：`/opt/ppanel`
- Nginx 配置：`/etc/nginx/sites-available/ppanel-api.conf`

需要上传这些文件 / 目录：

- `docker-compose.cloud.yml`
- `deploy/aws/ap-northeast-1/configs/ppanel.yaml.example` -> 重命名为 `configs/ppanel.yaml`
- `deploy/aws/ap-northeast-1/nginx/ppanel-api.conf`
- `grafana/`
- `loki/`
- `prometheus/`
- `tempo/`
- `.env.example` -> 重命名为 `.env`

目标目录示例：

```text
/opt/ppanel/
  docker-compose.cloud.yml
  .env
  configs/ppanel.yaml
  grafana/
  loki/
  prometheus/
  tempo/
  logs/
  cache/
  tempo_data/
```

## 7. 应用配置

基线模板见：

- [`configs/ppanel.yaml.example`](./configs/ppanel.yaml.example)
- [`nginx/ppanel-api.conf`](./nginx/ppanel-api.conf)

关键值必须替换：

- `MySQL.Addr`
- `MySQL.Password`
- `Redis.Host`
- `Redis.Pass`
- `JwtAuth.AccessSecret`
- `Administrator.Email`
- `Administrator.Password`
- `AppSignature.AppSecrets.*`
- `device.security_secret`
- `Site.Host`
- `Site.SiteName`

Redis 约定保持不变：

- 业务缓存：DB `0`
- Asynq：DB `5`

## 8. 部署步骤

### 8.0 创建东京基础设施

如果本机或跳板机已经配置好 AWS CLI 凭据，可以先直接执行：

```bash
cp deploy/aws/ap-northeast-1/configs/aws-jp-infra.env.example /root/aws-jp-infra.env
chmod 600 /root/aws-jp-infra.env
vim /root/aws-jp-infra.env

chmod +x deploy/scripts/aws_jp_create_base_infra.sh
bash deploy/scripts/aws_jp_create_base_infra.sh /root/aws-jp-infra.env
```

执行后可用下面命令随时核对东京底座状态：

```bash
chmod +x deploy/scripts/aws_jp_describe_state.sh
bash deploy/scripts/aws_jp_describe_state.sh /root/aws-jp-infra.env
```

### 8.1 初始化 EC2

把脚本上传到东京 EC2 后执行：

```bash
chmod +x deploy/scripts/bootstrap_aws_ec2.sh
sudo APP_DIR=/opt/ppanel APP_USER=ubuntu deploy/scripts/bootstrap_aws_ec2.sh
```

### 8.2 安装 Nginx 配置

```bash
sudo cp deploy/aws/ap-northeast-1/nginx/ppanel-api.conf /etc/nginx/sites-available/ppanel-api.conf
sudo ln -sf /etc/nginx/sites-available/ppanel-api.conf /etc/nginx/sites-enabled/ppanel-api.conf
sudo nginx -t
sudo systemctl reload nginx
```

### 8.3 启动容器

```bash
cd /opt/ppanel
docker compose -f docker-compose.cloud.yml up -d
```

### 8.4 预检

```bash
chmod +x deploy/scripts/preflight_aws_jp.sh
APP_DIR=/opt/ppanel \
RDS_HOST=<TOKYO_RDS_ENDPOINT> \
REDIS_HOST=127.0.0.1 \
deploy/scripts/preflight_aws_jp.sh
```

## 9. 数据迁移与切换

正式迁移请按：

- [`ops/hifast-aws-jp-migration-runbook-zh.md`](/Users/Apple/code_vpn/vpn/ppanel-server/ops/hifast-aws-jp-migration-runbook-zh.md)

执行。

核心原则：

- 先搭平行环境
- 停机后再导出香港主数据
- 东京验收通过后再切正式域名
- 切换后再重挂 `104` 灾备

## 10. 104 灾备节点常用模板

如果迁移完成后要把 `104.238.220.230` 重挂为东京主站从库，可复用：

- [`deploy/scripts/hifast_mysql_seed_primary_and_replica.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_mysql_seed_primary_and_replica.sh)
- [`deploy/scripts/hifast_mysql_attach_replica.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_mysql_attach_replica.sh)
- [`deploy/scripts/hifast_redis_attach_replica.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_redis_attach_replica.sh)
- [`deploy/scripts/hifast_data_sync_tool.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_data_sync_tool.sh)
- [`configs/replica-ops.env.example`](./configs/replica-ops.env.example)

## 11. 东京资源创建前置检查

在 AWS 控制台里至少先确认：

- 东京区已启用
- `ap-northeast-1` 可创建 `t4g.large`
- `ap-northeast-1` RDS 可创建 `db.r7g.xlarge`
- ACM / ALB / WAF / S3 服务在东京区可正常使用
- Tokyo 对应配额满足：
  - On-Demand Standard vCPU
  - ALB 数量
  - Elastic IP（如需）
  - RDS 实例数

## 12. 当前已知真实进度

截至 `2026-05-20`，已知状态如下：

- 东京 VPC `ppanel-jp-prod` 已创建
- VPC ID: `vpc-0846b23b4a7d64eac`
- VPC CIDR: `10.20.0.0/16`
- 4 个子网在 AWS 控制台里曾填写完成，但提交时控制台 session 失效
- 因此：
  - 子网是否真正创建成功，需要重新核实
  - IGW / 路由表 / 安全组 / RDS / EC2 / ALB / WAF 都应按“未完成”处理，重新复核

实时状态请以后续更新的 [`configs/resource-inventory.current.md`](./configs/resource-inventory.current.md) 为准。