# 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` / `provision_minio.sh` 的 `MINIO_ROOT_USER/PASSWORD` | 勿用默认 `minioadmin/minioadmin` |
| ☐ | **MinIO 业务密钥（后端）** | `config.env:MINIO_ACCESS_KEY / MINIO_SECRET_KEY` + `provision_minio.sh:MINIO_ACCESS_KEY/SECRET_KEY` | 账号 `fwh-toolbox`，写 `fwh-toolbox*` 桶；两处须一致 |
| ☐ | **MinIO AI 密钥（MCP）** | `config.mcp.env:MINIO_ACCESS_KEY / MINIO_SECRET_KEY` + `provision_minio.sh:MINIO_AI_ACCESS_KEY/SECRET_KEY` | 账号 `fwh-toolbox-ai`，写 `fwh-toolbox-ai*` 桶；默认账号=密码 |
| ☐ | **postgres 超级用户密码** | `install_pgadmin.sh:POSTGRES_PASSWORD` | 供 pgAdmin4 登录连接；勿用默认占位 |
| ☐ | **pgAdmin4 登录密码** | `install_pgadmin.sh:PGADMIN_PASSWORD` | Web 登录口令（邮箱 `liang_jlyx@163.com`） |
| ☐ | **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 的 `你的域名` | 反向代理入口 |
| ☐ | **Caddy DNS 凭据** | `install_caddy.sh:LIBDNS_SPACESHIP_APIKEY/APISECRET` | spaceship DNS-01 签证书；写入 systemd 服务，勿提交仓库 |
| ☐ | **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`（与建桶一致） |
| ☐ | MinIO AI bucket | `fwh-toolbox-ai-file` | `provision_minio.sh:MINIO_AI_BUCKET` / `filestore.AIFileBucket` |
| ☐ | pgAdmin4 端口 | `5480`（仅绑 `127.0.0.1`） | `install_pgadmin.sh:PGADMIN_PORT/PGADMIN_BIND` |
| ☐ | 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='强口令' deploy/scripts/init_databases.sh`（PG 建表 + Mongo/Redis 检查，不含 MinIO）
- ☐ 验证：`psql -d fwh_toolbox_db -c "\dt alarm_snapshot.*"`
- ☐ 创建 MinIO 桶 + 业务账号与策略：`MINIO_ROOT_USER=... MINIO_ROOT_PASSWORD=... MINIO_SECRET_KEY='强口令' MINIO_AI_SECRET_KEY='强口令' deploy/scripts/provision_minio.sh`
- ☐ 验证：`mc ls fwhlocal/`（桶 `fwh-toolbox`、`fwh-toolbox-ai-file`）、`mc admin user list fwhlocal`（用户 `fwh-toolbox`、`fwh-toolbox-ai`）

### B4.1 pgAdmin4（可选，数据库 Web 管理）

- ☐ `POSTGRES_PASSWORD='强口令' PGADMIN_PASSWORD='强口令' deploy/scripts/install_pgadmin.sh`
- ☐ 按脚本提示确认 `pg_hba.conf` 允许 Docker 网段以 `scram-sha-256` 连接后 `systemctl reload postgresql`
- ☐ 访问 `http://127.0.0.1:5480`，用 `liang_jlyx@163.com` 登录，新建 Server 连本机 PG（用户 `postgres`）
- ☐ 确认未把 `5480` 暴露公网（如需远程，置于反向代理 + 访问控制之后）

### B5. 配置后端

- ☐ `cp deploy/config.env.example service/config.env`
- ☐ `cp deploy/config.mcp.env.example service/config.mcp.env`（MCP 用 `fwh-toolbox-ai` 账号）
- ☐ 按 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 + 生成站点配置：`CADDY_DOMAIN='你的域名' LIBDNS_SPACESHIP_APIKEY='xxx' LIBDNS_SPACESHIP_APISECRET='xxx' deploy/scripts/install_caddy.sh`
- ☐ 确认二进制 `deploy/bin/caddy` 含 spaceship 插件（脚本会校验），拷至 `/usr/bin/caddy`
- ☐ 站点：`/fwh-toolbox/*`→静态 8300、`/fwh-toolbox/api/*`→`localhost:8301`、`/casdoor/*`→`localhost:8010`
- ☐ 校验并重载：`caddy validate --config /etc/caddy/Caddyfile` + `systemctl reload caddy`
- ☐ 确认 systemd 服务 `/lib/systemd/system/caddy.service` 权限 600（含明文 DNS token）

### 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 / pgAdmin 与 postgres 占位口令等）均已改为强口令
- ☐ `config.env` 权限收紧，且**未**提交到 Git（含密钥/证书）
- ☐ 数据库/MinIO/Redis 仅监听本地或受信网段
- ☐ pgAdmin4（`5480`）未暴露公网；postgres 超级用户密码仅用于受控管理
- ☐ MinIO 业务账号最小权限：后端用 `fwh-toolbox`、MCP 用 `fwh-toolbox-ai`，未用 root 跑业务
- ☐ Caddy systemd 服务含明文 DNS token，权限 600 且未提交仓库
- ☐ 备份策略：PostgreSQL（`pg_dump`）、MongoDB（`mongodump`）、MinIO 数据目录