当 Web 控制台无法访问、登录策略误配置、升级异常、服务停止、端口冲突或需要维护窗口操作时，管理员可以通过 SSH 登录服务器，使用 dzctl 对 duizeAIO 进行救援、恢复和维护。
root 用户，或在命令前加 sudo。文档示例默认使用 sudo dzctl ...；如果当前已经是 root，可以省略 sudo。使用场景：登录服务器后不确定 duizeAIO 是否已正确安装，或者执行 dzctl 提示找不到命令。
which dzctl
ls -l /usr/local/bin/dzctl
dzctl help正常返回应包含 /usr/local/bin/dzctl。如果返回 dzctl: command not found，先检查 /usr/local/bin/dzctl 是否存在；如果文件存在，可直接执行 sudo /usr/local/bin/dzctl help。如果文件不存在，说明命令或安装目录不完整，应优先从安装包或外部备份恢复 dzctl、duize-core、duize-agent。
dzctl help
dzctl --help| 命令 | 用途 |
|---|---|
status [core|agent] | 检查 duize 服务状态 |
start [core|agent|all] | 启动 duize 服务 |
stop [core|agent|all] | 停止 duize 服务 |
restart [core|agent|all] | 重启 duize 服务 |
user-info | 查看访问地址、用户和初始密码状态 |
listen-ip | 切换 IPv4 / IPv6 监听 |
version | 查看版本和运行模式 |
update | 修改用户名、密码、端口等系统信息 |
reset | 取消登录限制、HTTPS、域名绑定、MFA、Passkey |
restore | 从最近一次升级快照回滚服务和数据 |
rescue | 离线诊断、系统修复、恢复点校验、DB 恢复和 AI Runbook |
uninstall | 卸载 duize 服务，高风险命令 |
| 场景 | 执行命令 | 成功判断 | 异常处理 |
|---|---|---|---|
| 检查全部服务 | sudo dzctl status all | Core 和 Agent 都显示 正在运行 | 任一项 已停止，执行 sudo dzctl start all |
| 登录页打不开 | sudo dzctl status core | Core 显示 正在运行 | Core 停止时执行 sudo dzctl start core，失败则查 core 日志 |
| 容器、网站、文件操作失败 | sudo dzctl status agent | Agent 显示 正在运行 | Agent 停止时执行 sudo dzctl start agent，仍失败则查 Docker、磁盘和 agent 日志 |
| 忘记地址、端口、用户 | sudo dzctl user-info | 返回系统地址、系统用户、系统密码 | 提示使用 sudo 表示权限不足；数据库错误时检查数据目录 |
| 忘记密码或管理员被锁 | sudo dzctl update password | 返回 修改成功！ | 按提示处理密码为空、长度不足、两次不一致、复杂度不符 |
| 端口冲突 | sudo dzctl update port | 返回新系统端口并尝试重启 core | 端口占用时换端口；访问失败时放行防火墙和云安全组 |
| MFA、Passkey、IP 或域名限制 | sudo dzctl reset mfasudo dzctl reset passkeysudo dzctl reset ipssudo dzctl reset domain | 无错误输出并回到命令行 | 不生效时执行 sudo dzctl restart core |
| HTTPS 证书或跳转异常 | sudo dzctl reset https | 写入后自动重启服务 | 改用 http://IP:端口 访问；重启失败时查 core 日志 |
| 升级事故回滚 | sudo dzctl restore | 出现 1/5 到 5/5 并返回 回滚成功！ | 暂无可回滚文件 表示没有升级快照，需从外部备份或安装包修复 |
适用现象：浏览器访问超时、拒绝连接、空白；升级或断电重启后控制台不可访问；SSH 仍可登录。
sudo dzctl status all正常返回示例：
[OK]Core: 正在运行
[OK]Agent: 正在运行异常返回示例：
[FAIL]Core: 已停止
[OK]Agent: 正在运行处理命令：
sudo dzctl start core
sudo dzctl status core
sudo dzctl user-info
sudo dzctl version如果地址是旧域名、HTTPS 证书异常或登录策略阻断，按下面顺序救援：
sudo dzctl reset domain
sudo dzctl reset https
sudo dzctl restart core
sudo dzctl user-inforeset domain 后仍访问旧域名：可能是浏览器缓存或 core 未重新加载，执行 sudo dzctl restart core。reset https 后应改用 http://IP:端口 访问。restart core 返回 [FAIL]：继续查看 systemctl status duize-core --no-pager 和 journalctl -u duize-core -n 200 --no-pager。sudo dzctl status agent
sudo dzctl start agent
sudo dzctl restart agent
sudo dzctl status all判断方式：Agent 显示 正在运行 但功能仍失败，继续检查 Docker、磁盘空间、数据目录权限和具体任务日志；如果启动或重启 Agent 返回 [FAIL]，查看 journalctl -u duize-agent -n 200 --no-pager。
适用现象：账号密码正确但仍被 MFA、Passkey、IP 白名单、域名绑定或 HTTPS 证书拦住。
sudo dzctl reset ips
sudo dzctl reset domain
sudo dzctl reset https
sudo dzctl reset mfa
sudo dzctl reset passkey
sudo dzctl update password
sudo dzctl restart core
sudo dzctl user-inforeset domain、reset ips、reset mfa、reset passkey 通常没有成功提示，只要没有错误输出并回到命令行，就表示数据库写入完成。不生效时重启 core。
sudo dzctl update port
sudo dzctl status core
sudo dzctl user-info
ss -lntp | grep ':新端口'| 返回内容 | 修复方式 |
|---|---|
错误: 输入的端口号必须在 1 到 65535 之间 | 重新输入有效端口。 |
错误: 该端口号正被占用 | 换端口，或先处理占用进程。 |
| 修改成功但访问失败 | 放行服务器防火墙和云安全组的新端口。 |
sudo dzctl listen-ip ipv4
sudo dzctl listen-ip ipv6IPv4 成功返回包含 tcp4 [0.0.0.0]；IPv6 成功返回包含 tcp6 [::]。如果切换成功但仍无法访问，检查服务状态、端口监听、防火墙、安全组和服务器是否已有 IPv6 地址。
sudo dzctl status all
sudo dzctl version
sudo dzctl restore确认提示出现时输入 y：
duize 将会恢复至上一个稳定版本，是否继续 [y/n]: y正常回滚会依次出现 1/5 到 5/5：
（1/5）开始从 /opt/duize/duize/tmp/upgrade/.../original 目录回滚 duize 服务及数据...
（2/5）duize 二进制回滚成功
（3/5）duize 脚本回滚成功
（4/5）duize 服务回滚成功
（5/5）duize 数据回滚成功
回滚成功！已回滚到 v2.x.x，正在重启服务，请稍候...回滚后执行：
sudo dzctl status all
sudo dzctl version
sudo dzctl user-info如果返回 暂无可回滚文件，表示没有可用升级快照，不能继续依赖 dzctl restore，应从外部备份或安装包修复。执行 restore 前如系统仍可操作，建议先备份 /opt/duize/duize/db 和 /opt/duize/duize/conf。
sudo dzctl status all
sudo dzctl stop all
# 执行备份、迁移或系统维护
sudo dzctl start all
sudo dzctl status all
sudo dzctl user-info[OK] 停止 ... 成功：服务已停止，可以继续维护。[OK] 启动 ... 成功：服务已启动，再用 status 复查。[FAIL]：服务管理器执行失败，查看对应服务状态和日志。sudo dzctl uninstall 会停止并移除 duize 服务、脚本和二进制文件；如果选择删除数据目录，会移除数据库、配置和运行数据。仅在确认下线、重装或彻底清理时使用。sudo dzctl uninstall第一段确认：卸载将会停止并移除 duize 服务，是否继续 [y/n]。第二段确认：是否删除 duize 数据目录 [y/n]。输入 n 会保留数据目录，适合重装前保留数据；输入 y 会删除数据目录。
| 返回内容或现象 | 判断 | 修复动作 |
|---|---|---|
正在运行 | 服务运行中 | 业务仍异常时继续查端口、日志、数据库或具体功能依赖。 |
已停止 | 服务未运行 | 执行 sudo dzctl start <core|agent|all>。 |
[FAIL] ... 失败 | 服务管理器执行失败 | 查看 systemctl status duize-core 或 systemctl status duize-agent，再查 journalctl。 |
请以 root 用户身份运行此脚本或使用 sudo 权限 | 权限不足 | 改用 sudo dzctl ... 或切换 root。 |
duize-core command is unavailable | 核心二进制不可用 | 检查 /usr/local/bin/duize-core，必要时从安装包或备份恢复。 |
错误: 初始化数据库连接失败 | 数据库文件不可读、路径错误或损坏 | 检查 /usr/local/bin/dzctl 中的 BASE_DIR、/opt/duize/duize/db/core.db 和权限；必要时回滚或从备份恢复。 |
暂无可回滚文件 | 没有升级回滚快照 | 改用外部备份、安装包修复或人工恢复。 |
dzctl rescue 是 Web 页面不可用时的系统修复入口。建议先用只读命令判断故障等级，再决定是否执行写入型修复。
| 等级 | 典型场景 | 第一条命令 | 下一步判断 |
|---|---|---|---|
| R0 | 服务正常，但页面被域名、IP、HTTPS、MFA、Passkey 或密码锁住。 | sudo dzctl rescue status | 如果访问限制命中，进入 fix-access。 |
| R1 | 只能 SSH，core / agent 部分异常、端口不通或运行目录漂移。 | sudo dzctl rescue doctor | 先读报告；需要修 service 时先 dry-run。 |
| R2 | core、agent、web gateway 全部不可用或 service 文件损坏。 | sudo dzctl rescue fix-services | 默认只输出修复计划；确认后才写入。 |
| R3 | core.db、agent.db 或 AI 相关 DB 损坏、缺失、quick_check 失败。 | sudo dzctl rescue verify-db | 只读校验；恢复前必须选择恢复点。 |
| R4 | 本机 DB 与恢复点都不可用，需要外部备份或人工灾备。 | sudo dzctl rescue list-restore-points | 若无可用恢复点，不应声称业务数据已恢复。 |
fix-access、fix-services --confirm FIX_SERVICES、rebuild-index --confirm REBUILD_INDEX、restore --confirm RESTORE_DB、install-sidecar --confirm INSTALL_SIDECAR 会改本机文件或数据库。执行前必须确认维护窗口、备份和管理员审批。下面每一行只给一条主命令。执行后根据输出里的 faultLevel、recommendedNextActions、changedFiles、quarantinePath 或错误信息决定下一步。
| 场景 | 只执行这一条命令 | 用途和成功判断 |
|---|---|---|
| 不知道系统坏到什么程度 | sudo dzctl rescue status | 输出 R0-R4 故障等级、摘要和推荐下一步。 |
| 要完整体检，不修改任何文件 | sudo dzctl rescue doctor | 检查 BASE_DIR、app.yaml、服务、DB、访问限制和恢复点。 |
| 要把体检结果发给管理员或售后 | sudo dzctl rescue export-report -o /tmp/duize-rescue-report.json | 生成 JSON 报告，适合回传分析；默认不写业务数据。 |
| 页面被域名、IP、HTTPS、MFA 或 Passkey 锁住 | sudo dzctl rescue fix-access | 创建 quarantine 后恢复访问限制；输出修改项和后续访问地址。 |
| 同时重置端口并恢复页面访问 | sudo dzctl rescue fix-access --port 9999 | 只在确认端口可用时使用；完成后放行防火墙和安全组。 |
| 通过文件重置管理员密码 | sudo dzctl rescue fix-access --reset-password-file /root/new-pass.txt | 避免密码出现在 shell history；成功后立即删除密码文件。 |
| 怀疑 service 文件、二进制权限或 BASE_DIR 漂移 | sudo dzctl rescue fix-services | 默认 dry-run，只列出计划和风险，不写入。 |
| 已审批，执行服务启动链修复 | sudo dzctl rescue fix-services --confirm FIX_SERVICES | 写入 service 文件、权限和 dzctl BASE_DIR；仍需复查服务状态。 |
| 业务 DB 不可用，需要先看有哪些恢复点 | sudo dzctl rescue list-restore-points | 从 rescue/index.json 或升级备份目录只读列出恢复点。 |
| 恢复点索引缺失或怀疑过期 | sudo dzctl rescue rebuild-index | 默认 dry-run，扫描恢复点并显示将写入的索引内容。 |
| 已审批，重建恢复点索引 | sudo dzctl rescue rebuild-index --confirm REBUILD_INDEX | 原子写入 rescue/index.json，不覆盖业务 DB。 |
| 当前 DB 或恢复点 DB 需要校验 | sudo dzctl rescue verify-db | 只读执行存在性、sha256、SQLite quick_check 和 schema 检查。 |
| 校验指定恢复点 | sudo dzctl rescue verify-db --restore-point <id> | 确认该恢复点能否用于 DB 恢复。 |
| 预览 DB 恢复，不真正写入 | sudo dzctl rescue restore --scope db --restore-point <id> | 默认 dry-run，展示将恢复的 DB 和风险。 |
| 维护窗口内执行 DB 恢复 | sudo dzctl rescue restore --scope db --restore-point <id> --confirm RESTORE_DB | 恢复前创建 quarantine；恢复后执行 verify-db 和 restart all。 |
| 业务服务不可用时留下本地救援报告 | sudo dzctl rescue sidecar | 生成 reports JSON 并追加 rescue/ledger.jsonl。 |
| 预览安装独立救援 sidecar | sudo dzctl rescue install-sidecar | 默认 dry-run，只展示 duize-rescue.service 写入计划。 |
| 已审批，安装独立救援 sidecar | sudo dzctl rescue install-sidecar --confirm INSTALL_SIDECAR | 写入 duize-rescue.service；仍需按维护规范 daemon-reload/start。 |
| 让系统生成可审批的修复计划 | sudo dzctl rescue ai-runbook | 输出诊断解释、分级修复计划和审批文本，不执行高危动作。 |
| 只允许 Runbook 执行低风险白名单动作 | sudo dzctl rescue ai-runbook --action verify-db --confirm RUNBOOK_ACTION | 白名单只包括 sidecar、list-restore-points、verify-db。 |
status、doctor、export-report、list-restore-points、verify-db、ai-runbook 默认不修改业务数据。/opt/duize/rescue/quarantine/<timestamp>/，保留 dzctl、配置、service 文件或 DB 的当前状态。--confirm FIX_SERVICES，索引重建必须带 --confirm REBUILD_INDEX，DB 恢复必须带 --confirm RESTORE_DB，sidecar 安装必须带 --confirm INSTALL_SIDECAR。ai-runbook 只生成计划；即使带 --action，也只允许执行低风险白名单动作，不会自动执行 fix-access、fix-services 或 DB restore。sudo dzctl rescue status、sudo dzctl status all 和 sudo dzctl user-info。sudo dzctl status all
sudo dzctl user-info
sudo dzctl version
sudo dzctl restart core
sudo dzctl restart agentsudo dzctl status all
sudo dzctl version
sudo dzctl restore
sudo dzctl status all
sudo dzctl version
sudo dzctl user-info每次救援后至少执行 sudo dzctl status all 和 sudo dzctl user-info，再用浏览器访问返回的系统地址。