3x-ui/docs/install-fix-checklist.md

install.sh 修复清单与逐项修复说明

说明

本文基于 docs/install-issue-assessment.md 的分级结果，结合 install.sh、x-ui.sh、update.sh、service 模板与项目核心配置/启动逻辑的交叉检查，整理出一份可执行的修复清单。

文档目标：

• 把问题清单转成“可落地的修复项”
• 标明每项修复是否需要联动改动
• 提前指出与现有代码约定的冲突点
• 给出最小可验证的验收方式

---

使用建议

• 优先处理 P0 / P1，再处理输入校验、引号和死代码
• 涉及 service 路径、自定义安装目录、MariaDB 首装流程的项，不建议只改 install.sh
• 涉及“是否强制 HTTPS”“是否保留默认 admin/admin”的项，属于产品行为决策，修复前先定策略

---

一、核心修复项

1. 修复端口占用检测逻辑

• 对应问题：P0-01
• 涉及文件：
  • install.sh
  • x-ui.sh
  • update.sh
• 修复说明：
  • 当前 ss / netstat 分支使用 awk '$4 ~ p {exit 0} END {exit 1}'，即使命中也会在 END 阶段返回失败。
  • 应统一改成可靠的布尔判断方式，例如：
    • 用 ss -ltn | awk ... 时使用状态变量控制退出码
    • 或直接用 grep -q
  • 三个脚本里有重复实现，必须一次性同步修改，避免菜单脚本和安装脚本行为不一致。
• 是否与项目代码冲突：否
• 是否会改变行为：会，但属于“从错误行为修正为正确行为”
• 验收点：
  • 在端口已被监听时能稳定返回“占用”
  • 在端口空闲时能稳定返回“空闲”
  • 三个脚本的检测结果一致

2. 修复 SSL 失败仍显示成功

• 对应问题：P0-02
• 涉及文件：
  • install.sh
• 修复说明：
  • prompt_and_setup_ssl 返回失败后，当前脚本仍会输出 HTTPS 地址和“SSL 已启用并配置”。
  • 至少要做到：
    • 根据返回值区分“SSL 成功 / SSL 失败”
    • 失败时不要显示成功文案
    • 失败时不要强制输出 https://...
  • 更进一步可以考虑：
    • 失败即中止安装
    • 或允许继续安装，但明确标记为“HTTP/未启用 SSL”
• 是否与项目代码冲突：否
• 是否会改变行为：会，安装摘要将不再“伪成功”
• 注意事项：
  • 运行时 Web 服务本身支持 HTTP fallback，因此此项修复应优先修正文案，不要未经确认直接改成“SSL 失败即安装失败”
• 验收点：
  • 证书签发失败时，摘要中不再出现“SSL 已启用”
  • 地址协议与实际生效状态一致

3. 修复 ssl_cert_issue 的成功判定方式

• 对应问题：P0-03
• 涉及文件：
  • install.sh
• 修复说明：
  • 现在通过 acme.sh --list | tail -1 推断“本次签发的是哪张证书”，这不可靠。
  • 更合理的修法：
    • 让 ssl_cert_issue() 在成功时直接返回本次域名
    • 或在函数内直接完成域名保存，不依赖外部再去猜
    • 或基于用户输入域名作为唯一可信来源，不再查列表尾项
• 是否与项目代码冲突：否
• 是否会改变行为：会，证书成功识别逻辑更严格
• 验收点：
  • 机器上存在多张证书时，脚本仍能准确识别本次域名
  • 不会因为列表最后一项不是当前域名而误写配置

4. 去除默认 admin/admin 安装行为

• 对应问题：P0-04
• 涉及文件：
  • install.sh
• 关联代码：
  • database/db.go
• 修复说明：
  • 当前脚本文案声称“留空自动生成”，实际却回退为 admin/admin。
  • 建议修法：
    • 用户名留空时默认 admin 可以接受，但应明确提示
    • 密码留空时必须随机生成
    • 若输入 rd，也应随机生成密码而不是回退默认值
    • 安装完成时明确输出最终用户名/密码
• 是否与项目代码冲突：否
• 是否会改变行为：是，默认安装体验会改变
• 注意事项：
  • 核心代码默认种子用户仍是 admin/admin，安装脚本只是覆盖它
  • 因此此项不要求先改 Go 代码，也能落地
• 验收点：
  • 留空安装时不再生成 admin/admin
  • 安装摘要里显示的密码与实际可登录密码一致

5. 重构 MariaDB 首装流程

• 对应问题：P0-05
• 涉及文件：
  • install.sh
• 关联代码：
  • main.go
  • config/config.go
  • web/service/setting.go
• 修复说明：
  • 当前流程是：
    1. 先按默认 SQLite 初始化和写配置
    2. 再把 dbType 改成 MariaDB
    3. 但没有做 SQLite → MariaDB 数据迁移
  • 这会导致“用户输入过的配置不一定落到最终使用的库”。
  • 推荐修法有两种：
    • 方案 A：保守修法
      • 首装统一先走 SQLite
      • 若用户选择 MariaDB，提示安装完成后执行明确迁移
      • 避免脚本伪装成“已直接落到 MariaDB”
    • 方案 B：彻底修法
      • 在项目代码里补一个“无 DB bootstrap 配置写入流程”
      • 先写 settings JSON，再按 dbType 初始化对应数据库
  • 如果只改脚本顺序，不改项目代码，风险仍然较高。
• 是否与项目代码冲突：有耦合，需要联动
• 是否会改变行为：是，尤其是 MariaDB 首装路径
• 验收点：
  • 首次选择 MariaDB 后，最终实际运行库中存在用户刚设置的账号/端口/路径
  • 不再出现“看似设置成功，实际登录不上”的情况

6. 修复 install_acme() 污染当前目录

• 对应问题：P0-06
• 涉及文件：
  • install.sh
• 修复说明：
  • install_acme() 进入 ~ 后不恢复当前目录，后续若依赖解压目录中的文件会出错。
  • 建议修法：
    • 函数内保存当前目录并在结束前恢复
    • 或彻底改成绝对路径，不依赖当前工作目录
• 是否与项目代码冲突：否
• 是否会改变行为：否，属于纯修复
• 验收点：
  • 安装 acme 之后，仍能从解压目录找到 service 文件
  • 安装过程中的后续 cp/cd 行为不再受影响

7. 统一 Arch 的安装路径与 service 路径

• 对应问题：P0-07
• 涉及文件：
  • install.sh
  • x-ui.service.arch
• 修复说明：
  • 当前脚本默认安装到 /usr/local/x-ui，但 Arch service 指向 /usr/lib/x-ui。
  • 修法应二选一：
    • 要么 Arch 平台真的安装到 /usr/lib/x-ui
    • 要么修改 Arch service 模板，让它和 xui_folder 保持一致
  • 推荐后者：统一用安装脚本渲染 service 路径，而不是靠固定模板硬编码。
• 是否与项目代码冲突：否，但与 service 模板强相关
• 是否会改变行为：会，从“默认可能起不来”变成“可正常启动”
• 验收点：
  • Arch 安装后 systemctl status x-ui 正常
  • service 的 WorkingDirectory 与 ExecStart 指向真实安装目录

8. 给删除安装目录增加安全保护

• 对应问题：P0-08
• 涉及文件：
  • install.sh
  • 建议同步评估 x-ui.sh
• 修复说明：
  • 当前直接 rm -rf ${xui_folder}/，若环境变量异常可能误删危险路径。
  • 建议加以下保护：
    • 变量不能为空
    • 不能是 /
    • 不能是 /usr、/usr/local 这类上层目录
    • 路径必须匹配预期模式
    • 统一加引号
• 是否与项目代码冲突：否
• 是否会改变行为：否，属于安全兜底
• 验收点：
  • 正常安装目录可删除
  • 危险目录会被拒绝并报错

---

二、联动修复项

9. 自定义安装目录支持做全链路统一

• 对应问题：P1-01、P1-11
• 涉及文件：
  • install.sh
  • x-ui.sh
  • update.sh
  • x-ui.service.debian
  • x-ui.service.rhel
  • x-ui.service.arch
  • x-ui.rc
• 修复说明：
  • 目前只有脚本变量允许覆盖安装目录，但 service 模板与部分流程仍硬编码路径。
  • 修法建议：
    • 统一把 service/init 文件改为模板渲染
    • 所有脚本都以 XUI_MAIN_FOLDER 为唯一事实来源
    • 不再通过 ${xui_folder%/x-ui} 推导工作目录
• 是否与项目代码冲突：否
• 是否会改变行为：会，自定义目录将真正可用
• 验收点：
  • 设置 XUI_MAIN_FOLDER 后，安装、升级、菜单、service 启动全部正常

10. 统一证书状态判定逻辑

• 对应问题：P1-07 及相关派生问题
• 涉及文件：
  • install.sh
  • web/web.go
  • web/html/settings.html
• 修复说明：
  • 当前前端和安装脚本在“何时算 HTTPS 启用”上判断过于宽松。
  • 运行时真实逻辑是：只有证书和私钥都能被加载，才会启用 TLS。
  • 修法建议：
    • 安装摘要中：必须 cert + key 都有效才显示 HTTPS
    • 前端跳转逻辑中：不要用 webCertFile || webKeyFile 判定 HTTPS
    • 可选地增加“证书路径存在但加载失败”的状态提示
• 是否与项目代码冲突：否，是向运行时行为靠拢
• 是否会改变行为：会，状态显示更严格
• 验收点：
  • 只有 cert/key 成对有效时才显示 HTTPS
  • 前端不会因为只填了一项路径就强跳 HTTPS

11. 同步修复脚本族中的重复问题

• 对应问题：重复逻辑导致的派生风险
• 涉及文件：
  • install.sh
  • x-ui.sh
  • update.sh
• 修复说明：
  • 多处辅助函数和路径逻辑是复制粘贴的。
  • 推荐修法：
    • 先列出三者重复函数：端口检测、域名/IP 校验、acme 检查、目录变量
    • 同批次修改，避免只修了安装脚本但菜单脚本/更新脚本依旧保留旧 bug
  • 长期建议是提取共享 shell 片段，但短期不一定需要重构。
• 是否与项目代码冲突：否
• 是否会改变行为：会，让相关脚本行为一致
• 验收点：
  • 同一类操作在三个脚本中的表现一致

---

三、需要先做产品决策的修复项

12. 决定 SSL 失败时是否中止安装

• 对应问题：P0-02 的策略层延伸
• 涉及文件：
  • install.sh
  • 间接关联 web/web.go
• 修复说明：
  • 当前脚本文案把 SSL 描述成“必需”，但运行时实际上支持 HTTP。
  • 修复前要先定策略：
    • 策略 A：SSL 失败仍允许安装
      • 但必须准确提示“当前为 HTTP”
    • 策略 B：SSL 失败即安装失败
      • 真正把 SSL 变成安装前置条件
  • 两种都能实现，但这是产品行为选择，不是单纯 bugfix。
• 是否与项目代码冲突：否
• 是否会改变行为：是
• 验收点：
  • 安装流程与产品定义一致
  • 文案、输出地址、最终服务状态三者一致

13. 决定默认凭据策略

• 对应问题：P0-04
• 涉及文件：
  • install.sh
  • 间接关联 database/db.go
• 修复说明：
  • 需要明确项目策略是：
    • 保留默认用户名 admin
    • 默认密码随机
    • 还是用户名、密码都随机
  • 一旦确定，应同步修改：
    • 安装提示
    • 安装完成摘要
    • 相关文档
• 是否与项目代码冲突：否
• 是否会改变行为：是
• 验收点：
  • 安装体验符合预期
  • 登录凭据输出准确、可复现

14. 决定是否正式支持“首装直连 MariaDB”

• 对应问题：P0-05
• 涉及文件：
  • install.sh
  • main.go
  • config/config.go
  • web/service/setting.go
• 修复说明：
  • 若确认保留这个能力，建议不要再依赖“先 InitDB 再改 dbType”的间接流程。
  • 更合理的做法是引入正式 bootstrap：
    • 先生成 settings JSON
    • 再依据 dbType 初始化数据库
    • 再写用户与面板基础配置
  • 若短期不想改 Go 代码，则建议安装脚本暂时不要把“MariaDB 首装直连”包装成已完整支持。
• 是否与项目代码冲突：有实现耦合
• 是否会改变行为：是
• 验收点：
  • 首装 MariaDB 路径不再依赖 SQLite 中间态

---

四、低风险可批量修复项

15. 给关键命令补错误检查

• 对应问题：P1-02、P1-03、P1-04
• 涉及文件：
  • install.sh
• 修复说明：
  • tar、cd、config_after_install、依赖安装等关键步骤都应显式校验返回值。
  • 建议统一模式：
    • 关键命令失败立即退出
    • 输出明确错误原因
• 是否与项目代码冲突：否
• 是否会改变行为：会，更早失败、更容易定位问题
• 验收点：
  • 任一关键步骤失败时，脚本立即停止并给出准确信息

16. 修复路径和变量未加引号

• 对应问题：P2-18
• 涉及文件：
  • install.sh
  • x-ui.sh
  • update.sh
• 修复说明：
  • 所有路径、URL、证书目录、安装目录、环境变量路径都应统一加引号。
  • 尤其是：
    • rm -rf
    • cp
    • mv
    • chmod
    • 执行 ${xui_folder}/x-ui
• 是否与项目代码冲突：否
• 是否会改变行为：通常不会，只提升稳健性
• 验收点：
  • 自定义目录、带空格路径时脚本仍工作正常

17. 修复手动端口输入默认值与数字校验

• 对应问题：P2-05、P2-06、P2-07
• 涉及文件：
  • install.sh
• 修复说明：
  • 用户回车时应自然使用默认端口，而不是走“无效输入”
  • 所有端口输入统一做：
    • 去空格
    • 数字校验
    • 1-65535 范围校验
    • 端口占用校验
• 是否与项目代码冲突：否
• 是否会改变行为：会，交互更合理
• 验收点：
  • 空输入能正确落默认值
  • 非数字输入会被拒绝
  • 冲突端口会被识别

18. 修复公网 IP 获取失败后的交互路径

• 对应问题：P2-12
• 涉及文件：
  • install.sh
• 修复说明：
  • 当前 server_ip 获取失败后，IP 证书路径依然可能被当作默认路径。
  • 建议修法：
    • 获取失败时提示用户手动输入 IPv4
    • 或自动把默认 SSL 选项切到域名/自定义证书
    • 至少不能继续伪装“默认可走 IP 证书”
• 是否与项目代码冲突：否
• 是否会改变行为：会，失败路径更明确
• 验收点：
  • IP 获取失败时不会再生成空主机名 URL

19. Cloudflare API Key 改为静默输入并清理环境变量

• 对应问题：P2-13、P2-14
• 涉及文件：
  • install.sh
• 修复说明：
  • API Key 应使用静默输入
  • 导出环境变量后应在流程结束时 unset
  • 域名也应走 is_domain 校验
• 是否与项目代码冲突：否
• 是否会改变行为：会，更安全
• 验收点：
  • 终端不会明文回显 API Key
  • 函数结束后环境变量不残留

20. 清理死代码与误导注释

• 对应问题：P3-01、P3-02、P3-03、P3-05、P3-06、P3-07、P3-08
• 涉及文件：
  • install.sh
• 修复说明：
  • 删除未使用变量与未接入函数
  • 修正不准确注释和提示文案
  • 调整 bash 风格问题（如 == 0 → -eq 0 这类可读性优化）
• 是否与项目代码冲突：否
• 是否会改变行为：通常不会
• 验收点：
  • 代码更容易维护，输出文案与实际逻辑一致

---

五、建议执行顺序

第一批：立即修

• 修复端口检测
• 修复 SSL 伪成功
• 修复 install_acme 目录污染
• 修复 Arch service 路径
• 修复危险删除逻辑

第二批：联动修

• 自定义安装目录全链路支持
• 三个 shell 脚本重复逻辑同步修复
• 证书状态判定统一到运行时真实行为

第三批：策略确认后再修

• SSL 失败是否中止安装
• 默认凭据策略
• MariaDB 首装是否正式支持

第四批：批量清理

• 输入校验
• 错误检查
• 引号与安全性
• 死代码与注释

---

六、最小验收清单

• install.sh、x-ui.sh、update.sh 的端口检测结果一致
• 证书失败时安装摘要不再伪装 HTTPS 成功
• Arch / Debian / RHEL / Alpine 的 service/init 路径与实际安装目录一致
• 自定义 XUI_MAIN_FOLDER 后，安装、升级、菜单脚本都能正常工作
• 选择 MariaDB 时，最终实际使用的数据库中存在用户刚输入的配置
• 密码留空不再回退 admin/admin
• Cloudflare API Key 不再明文输入
• 公网 IP 获取失败时，默认流程不会给出空地址或错误 HTTPS 地址