Etusivu Tutki Apua
Rekisteröidy Kirjaudu sisään
FWH
/
FranklinWH-Toolbox
2
0
Fork 0
Tiedostot Ongelmat 0 Pull-pyynnöt 0 Wiki
Haara: master
Haarat Tagit
FranklinWH-Tool...
/
deploy
/
CHECKLIST.md

CHECKLIST.md 9.0 KB
Pysyvä linkki Historia Raaka

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