# FranklinWH Toolbox 部署清单（CHECKLIST）

本清单汇总从零部署所需**填写/确认的内容**与**执行步骤**，可逐项打勾。
详细说明见 [DEPLOYMENT.md](./DEPLOYMENT.md)。脚本中对应位置均有 `# TODO:` 注释，
可用以下命令快速定位：

```bash
grep -rn 'TODO' deploy/scripts deploy/config.env.example
```

图例：**[必填]** 不填无法运行/有安全风险 ｜ **[确认]** 有默认值需核对 ｜ **[可选]** 用到才填

---

## A. 需要你填写/确认的内容

### A1. 密码与密钥（必填，安全相关）

| # | 项目 | 位置 | 说明 |
|---|------|------|------|
| ☐ | **PostgreSQL 业务口令** | `init_databases.sh:PG_FWH_PASSWORD` + `config.env:POSTGRES_DSN` | `fwh_toolbox` 角色密码，两处必须**完全一致** |
| ☐ | **MinIO 管理员账户** | `install_deps.sh` / `init_databases.sh` 的 `MINIO_ROOT_USER/PASSWORD` | 勿用默认 `minioadmin/minioadmin` |
| ☐ | **MinIO 业务密钥** | `config.env:MINIO_ACCESS_KEY / MINIO_SECRET_KEY` | 后端访问对象存储用 |
| ☐ | **FWH 生产账号** | `config.env:FWH_USER / FWH_PASSWORD` | 密码填明文，后端自动 MD5 |
| ☐ | **Casdoor 数据库口令** | `install_casdoor.sh:CASDOOR_PG_PASSWORD` | 勿用默认 `casdoor` |

### A2. 证书文件（必填）

| # | 项目 | 位置 | 说明 |
|---|------|------|------|
| ☐ | **FWH 生产 MQTT 证书** | `server/cert/pro/`（CA/crt/key 三件） | 路径与 `config.env:FWH_MQTT_CA/CERT/KEY` 对应 |
| ☐ | **Casdoor 应用证书** | Casdoor 后台获取的 X.509 PEM | 后端用于校验 JWT 签名（见 A4） |

### A3. 域名与网络（必填）

| # | 项目 | 位置 | 说明 |
|---|------|------|------|
| ☐ | **对外域名** | Caddyfile 的 `你的域名` | 反向代理入口 |
| ☐ | **Casdoor origin/回调** | `install_casdoor.sh:CASDOOR_ORIGIN` + Casdoor 应用 Redirect URLs | 如 `https://<域名>/casdoor`；回调 `https://<域名>/fwh-toolbox/casdoor/callback` |
| ☐ | **远端只读 MySQL** | `config.env:MYSQL_DSN` | 用到站点信息查询功能时**必填**；替换 USER/PASSWORD/HOST/PORT |

### A4. Casdoor 应用信息（必填）

| # | 项目 | 说明 |
|---|------|------|
| ☐ | 创建组织 `organization_franklinwh_toolbox` | 名称必须与前后端硬编码一致 |
| ☐ | 创建应用 `app-franklinwh-toolbox` | 记录 Client ID / Client Secret / 证书 |
| ☐ | 同步到源码（仅新建应用时） | `service/utils/casdoor/casdoor.go`（endpoint/clientId/clientSecret/certificate）与 `src/utils/casdoor/casdoor.ts`（ClientId），改后需**重新构建**前后端 |

> ⚠️ 沿用现有 Casdoor 应用可跳过 A4 的源码修改；新建应用则必须改源码后重编译。

### A5. 需确认的默认值

| # | 项目 | 默认 | 位置 |
|---|------|------|------|
| ☐ | 部署根目录 | `/var/www/fwh-toolbox` | `setup.sh` / `deploy.sh:DEPLOY_ROOT` |
| ☐ | 后端运行用户 | 当前用户 | `RUN_USER` / `config.env:KIRO_RUN_AS_USER` |
| ☐ | 后端端口 | `8301` | `config.env:APP_PORT` |
| ☐ | Asynqmon 端口 | `8302` | `config.env:ASYNQMON_PORT` |
| ☐ | MinIO 端口 | `9198`/`9199` | `install_deps.sh` |
| ☐ | Casdoor 端口 | `8010` | `install_casdoor.sh:CASDOOR_PORT` |
| ☐ | 运行环境 | `dev` | `config.env:APP_ENV`（生产改 `pro`） |
| ☐ | Mongo 库名 | `FwhToolboxDb` | `config.env:MONGO_DSN`（开发 `FwhToolboxDbDev`） |
| ☐ | MinIO bucket | `fwh-toolbox` | `config.env:MINIO_BUCKET_NAME`（与建桶一致） |
| ☐ | Kiro 用户/HOME | `jerry-remote` | `config.env:KIRO_RUN_AS_USER/KIRO_HOME` |

### A6. 可选功能

| # | 项目 | 位置 | 说明 |
|---|------|------|------|
| ☐ | FWH 测试环境 | `config.env:FWH_TEST_*` + `server/cert/test/` | 连测试服才填 |
| ☐ | Plane 集成 | `config.env:PLANE_*` | 启用反馈/任务同步才填 |

---

## B. 部署步骤清单

> 推荐直接用交互式向导 `deploy/scripts/setup.sh`，它会逐项提示 A 节内容。
> 以下为等价的分步操作，可据此逐项打勾。

### B1. 前置环境

- ☐ 目标机为 Ubuntu（参考 22.04），当前用户具备 `sudo` 权限
- ☐ （远程部署）本机可 SSH 到目标机，已准备好私钥或密码
- ☐ 已克隆代码到目标机（或本机构建后上传）

### B2. 安装依赖（数据库引擎 + Docker）

- ☐ 运行 `DETECT_ONLY=1 deploy/scripts/install_deps.sh` 检测现状
- ☐ 安装缺失项：PostgreSQL 14 / MongoDB 8.0 / Redis / MinIO + mc / Docker
- ☐ 确认服务已运行：`systemctl status postgresql mongod redis-server minio docker`

### B3. 安装并配置 Casdoor

- ☐ `CASDOOR_PG_PASSWORD='强口令' deploy/scripts/install_casdoor.sh`
- ☐ 配置宿主 PostgreSQL 允许容器连接（`listen_addresses` + `pg_hba.conf`，见 DEPLOYMENT.md 10.2）
- ☐ 登录 Casdoor（默认 admin/123，**立即改密**），完成 A4 的组织/应用配置
- ☐ 配置反向代理 `/casdoor`（见 B7）

### B4. 初始化数据库

- ☐ `PG_FWH_PASSWORD='强口令' MINIO_ROOT_USER=... MINIO_ROOT_PASSWORD=... deploy/scripts/init_databases.sh`
- ☐ 验证：`psql -d fwh_toolbox_db -c "\dt alarm_snapshot.*"`、`mc ls fwhlocal/`

### B5. 配置后端

- ☐ `cp deploy/config.env.example service/config.env`
- ☐ 按 A 节逐项填写 `config.env`（搜索文件内 `TODO`）
- ☐ 放置 MQTT 证书到 `service/cert/pro/`（及 `test/`）

### B6. 构建并部署前后端

- ☐ `deploy/scripts/deploy.sh backend`（构建二进制 + systemd 服务）
- ☐ `deploy/scripts/deploy.sh frontend`（构建 dist + 同步静态目录）
- ☐ 或一次性 `deploy/scripts/deploy.sh all`

### B7. 反向代理（Caddy）

- ☐ 安装 Caddy 2
- ☐ 配置站点：`/fwh-toolbox/*`→静态、`/fwh-toolbox/api/*`→`localhost:8301`、`/casdoor/*`→`localhost:8010`
- ☐ 把 `你的域名` 替换为实际域名，`systemctl reload caddy`

### B8. 验证

- ☐ 后端：`curl http://127.0.0.1:8301/swagger/index.html`
- ☐ 任务面板：`curl http://127.0.0.1:8302/asynqmon/`
- ☐ Casdoor：`curl http://127.0.0.1:8010/`
- ☐ 前端（经反代）：`curl -k https://<域名>/fwh-toolbox/`
- ☐ 登录流程：访问前端 → 跳转 Casdoor 登录 → 回调成功
- ☐ 日志无异常：`journalctl -u fwh-toolbox-server -f`

---

## C. 安全收尾

- ☐ 所有默认口令（minioadmin / casdoor / admin@123 等）均已改为强口令
- ☐ `config.env` 权限收紧，且**未**提交到 Git（含密钥/证书）
- ☐ 数据库/MinIO/Redis 仅监听本地或受信网段
- ☐ 备份策略：PostgreSQL（`pg_dump`）、MongoDB（`mongodump`）、MinIO 数据目录