FranklinWH-Toolbox/deploy/CHECKLIST.md

FranklinWH Toolbox 部署清单（CHECKLIST）

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

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 数据目录