详细指导¶

本文档面向最终用户、实施人员、运维人员，介绍私有部署的完整流程、支持范围、常用命令与常见问题。

文档概要¶

本指南用于在全新 Linux 服务器上部署整套系统：

• IAM（认证与用户中心）
• EZtCloud
• EZtView（可选）

前置条件¶

请先阅读并确认：

• 前置条件

一次性下载安装并启动部署向导¶

mkdir -p /workspace
cd /workspace
rm -rf /workspace/isw-helper

git clone https://gitee.com/hotanzn/isw-helper.git
cd /workspace/isw-helper

python3 deploy_all.py

执行后，会启动交互式部署向导：

1. 自动探测服务器可用 IP 并供您选择。
2. 检查并自动安装基础依赖。
3. 准备必要目录和凭证文件。
4. 启动或安装 PostgreSQL 15 容器。
5. 拉取 IAM / EZtCloud / EZtView 的运行时代码。
6. 调用各项目的 deploy/install.py 完成容器编排与初始化。
7. 自动创建 IAM OAuth2 客户端并写入凭证文件。

如需无人值守，可使用 --assume-yes。

deploy_all.py 常用方式¶

全自动部署¶

cd /workspace/isw-helper
python3 deploy_all.py --assume-yes

指定部署 IP¶

python3 deploy_all.py --ip 192.168.1.100 --assume-yes

只部署 IAM + EZtCloud（不安装 EZtView）¶

python3 deploy_all.py --only-iam-eztcloud --assume-yes

自动模式下跳过 EZtView¶

python3 deploy_all.py --skip-mcq --assume-yes

凭证文件说明¶

部署过程中会生成凭证文件：

• 路径：/workspace/isw-helper/output/deploy_credentials.json
• 权限：600（仅 root 可读写）

建议部署后将该文件备份到安全位置并严格控制访问权限。

查看超管密码（get_admin_password.py）¶

当需要快速获取已部署环境中的超管密码时，可使用 get_admin_password.py 直接读取凭证文件中的 iam_admin.password。

注意：如果密码已被手动修改，则此方法不可用。

使用命令¶

cd /workspace/isw-helper
python3 get_admin_password.py

执行后将直接输出密码，例如：

password

说明与注意事项¶

• 读取来源：/workspace/isw-helper/output/deploy_credentials.json
• 输出内容仅为密码本身，便于复制到登录页面或后续自动化脚本
• 请避免在共享终端、录屏或公开日志中直接执行，防止密码泄露
• 如提示未找到凭证文件，请先确认部署已完成且凭证文件存在

部署后修改服务器 IP（change_ip.py）¶

当系统已经完成内网部署，但服务器 IP 发生变化时，可使用 isw-helper/change_ip.py 自动处理常见改 IP 操作，避免手工逐项修改配置。

适用场景¶

适用于以下场景：

• 首次部署时使用了临时 IP，后续切换为正式 IP
• 服务器更换了内网 IP
• 虚拟机迁移后 IP 发生变化
• 需要统一更新 IAM、EZtCloud、EZtView 相关配置中的旧 IP

使用前准备¶

建议在执行前确认以下事项：

• 已使用 root 或具备足够权限的用户执行
• iam_web_server 容器处于运行状态，否则 IAM 数据库中的相关配置可能无法自动更新
• 建议提前做好整机或关键配置备份

基本用法¶

cd /workspace/isw-helper
python3 change_ip.py --old-ip 192.168.1.23 --new-ip 192.168.23.152

参数说明¶

• --old-ip：部署时使用的旧 IP 地址，必填
• --new-ip：要切换到的新 IP 地址，必填
• --workspace：工作目录，默认为 /workspace

执行结果说明¶

脚本执行完成后，会输出：

• 本次被修改的文件列表
• 处理过程中的错误信息（如有）
• 自动生成的备份目录路径

备份目录命名格式类似：

• /workspace/ip_change_backup_20260423_153000

如修改后发现异常，可参考备份目录中的文件进行人工比对和恢复。

注意事项¶

• 脚本仅校验 IP 地址格式，不会校验新旧 IP 是否真实可达
• EMQX connector 更新依赖 isw_v2/backend/.env 中的以下配置：
• EMQX_API_HOST
• EMQX_API_PORT
• EMQX_ACCOUNT
• EMQX_PASSWORD
• API_HOST
• 如果未找到指定的 EMQX connector，脚本会跳过该步骤并输出提示
• IAM 数据库更新优先通过运行中的 iam_web_server 容器执行；若容器不可用，脚本不会继续回退到宿主机环境执行
• 重启脚本执行失败时，其余已完成的配置修改不会自动回滚，请根据备份文件手工恢复
• 建议在业务低峰期执行，并在执行后重点验证登录、设备接入、页面访问、Webhook 回调等功能是否正常

推荐执行后检查¶

建议在执行完成后至少检查以下内容：

• IAM、EZtCloud、EZtView 页面是否可正常打开
• 平台中的接口地址、回调地址是否已切换为新 IP
• 设备 MQTT / HTTP 接入是否恢复正常
• EMQX webhook 是否仍能正常回调平台
• 如使用反向代理或防火墙，请同步确认对应策略已放通新 IP

完全清理环境（cleanup_all.py）¶

如需完全卸载并回到初始状态：

cd /workspace/isw-helper
python3 cleanup_all.py

非交互清理（危险）：

python3 cleanup_all.py --assume-yes

额外删除镜像：

python3 cleanup_all.py --remove-images

常见问题¶

提示不是 root 用户¶

请先执行：

sudo -i

CentOS 7 yum 源异常（如 mirrorlist/baseurl 错误）¶

可执行修复脚本：

cd /workspace/isw-helper
bash fix_centos7_yum_repos.sh

若仍异常，请切换到可用镜像源（阿里云 / 腾讯云 / 内网镜像 / vault）后重试。

如在使用过程中遇到其他问题，请保留实际步骤与报错信息，并联系技术支持。