3x-ui/docs/install-logic.md

install.sh 逻辑文档

概述

install.sh 是 3x-ui 面板的安装脚本，负责在 Linux 服务器上完成以下工作：

1. 安装系统依赖包
2. 下载并解压 3x-ui 发行版
3. 配置 systemd / OpenRC 服务
4. 生成随机凭据（用户名、密码、端口、Web 路径）
5. 配置 SSL 证书（Let's Encrypt 域名证书、IP 证书、或自定义证书）
6. 显示安装结果和访问信息

---

全局配置

颜色变量

变量	值	用途
red	\033[0;31m	红色文本
green	\033[0;32m	绿色文本
blue	\033[0;34m	蓝色文本
yellow	\033[0;33m	黄色文本
plain	\033[0m	重置颜色

路径变量

变量	默认值	说明
xui_folder	/usr/local/x-ui	x-ui 安装目录
xui_service	/etc/systemd/system	systemd 服务文件目录

可通过环境变量 XUI_MAIN_FOLDER 和 XUI_SERVICE 覆盖。

---

入口流程

install.sh 被执行
  ├─ 检查 root 权限
  ├─ 检测操作系统发行版
  ├─ 检测 CPU 架构
  ├─ install_base()          ← 安装系统依赖
  └─ install_x-ui($1)        ← 主安装逻辑（$1 为可选的版本号）

---

函数详解

1. root 权限检查（第 14-15 行）

检查 $EUID 是否为 0。非 root 用户直接退出并提示使用 root 权限。

2. 操作系统检测（第 17-28 行）

读取 /etc/os-release 或 /usr/lib/os-release，将 $ID 赋值给 release 变量。

支持的发行版：

包管理器	发行版
apt	ubuntu, debian, armbian
dnf	fedora, amzn, virtuozzo, rhel, almalinux, rocky, ol
yum	centos 7
pacman	arch, manjaro, parch
zypper	opensuse-tumbleweed, opensuse-leap
apk	alpine

3. arch() — CPU 架构检测（第 30-41 行）

通过 uname -m 映射到标准架构标识：

uname -m 输出	返回值
x86_64, x64, amd64	amd64
i*86, x86	386
armv8*, arm64, aarch64	arm64
armv7*, arm	armv7
armv6*	armv6
armv5*	armv5
s390x	s390x
其他	退出报错

4. IP/域名验证函数（第 46-57 行）

函数	逻辑
is_ipv4()	正则匹配 数字.数字.数字.数字 格式
is_ipv6()	检查字符串是否包含 :
is_ip()	调用 is_ipv4 或 is_ipv6
is_domain()	正则匹配标准域名格式（含国际化域名 xn-- 支持）

5. is_port_in_use() — 端口占用检测（第 60-74 行）

按优先级尝试三种方式：

1. ss -ltn — 检查监听端口
2. netstat -lnt — 回退方案
3. lsof -nP -iTCP:端口 -sTCP:LISTEN — 最后手段

任一命中即返回 0（端口被占用）。

6. install_base() — 安装基础依赖（第 76-104 行）

根据 $release 使用对应的包管理器安装以下公共依赖：

curl, tar, tzdata, socat, ca-certificates, openssl

额外安装 cron（用于 acme.sh 自动续期，仅 apt 系列）。

• CentOS 7 使用 yum，其他版本使用 dnf
• 未识别的发行版默认回退到 apt-get

7. gen_random_string(length) — 随机字符串生成（第 106-111 行）

openssl rand -base64(length*2) → 过滤 a-zA-Z0-9 → 截取前 length 个字符

用于生成用户名、密码、Web 路径等随机值。

8. install_acme() — 安装 acme.sh（第 113-124 行）

curl -s https://get.acme.sh | sh

安装到 ~/.acme.sh/ 目录。失败返回 1。

---

SSL 证书管理

9. setup_ssl_certificate(domain, server_ip, port, webBasePath) — 域名 SSL（第 126-191 行）

用途：为域名签发 Let's Encrypt 证书。

流程：

检查 acme.sh 是否已安装
  ├─ 未安装 → 调用 install_acme()
  └─ 已安装 → 继续

创建证书目录：/root/cert/${domain}/

签发证书：
  acme.sh --set-default-ca --server letsencrypt
  acme.sh --issue -d ${domain} --listen-v6 --standalone --httpport 80
  ↳ 失败 → 清理并返回 1

安装证书：
  acme.sh --installcert
    --key-file     /root/cert/${domain}/privkey.pem
    --fullchain-file /root/cert/${domain}/fullchain.pem
    --reloadcmd    "systemctl restart x-ui"

启用自动续期：acme.sh --upgrade --auto-upgrade

设置文件权限：
  privkey.pem  → 600（仅所有者可读）
  fullchain.pem → 644

配置面板证书路径：
  x-ui cert -webCert fullchain.pem -webCertKey privkey.pem

前提条件：80 端口必须可从外网访问。

10. setup_ip_certificate(ipv4, ipv6) — IP 证书（第 195-343 行）

用途：为 IP 地址签发 Let's Encrypt 短期证书（约 6 天有效期）。

流程：

检查 acme.sh
验证 IPv4 地址格式

创建证书目录：/root/cert/ip/

选择 HTTP-01 监听端口：
  └─ 默认 80，用户可自定义
  └─ 循环检测端口占用，被占用则提示换端口

签发证书：
  acme.sh --issue
    -d ${ipv4} [-d ${ipv6}]
    --standalone
    --server letsencrypt
    --certificate-profile shortlived
    --days 6
    --httpport ${WebPort}

安装证书：
  acme.sh --installcert
    --key-file     /root/cert/ip/privkey.pem
    --fullchain-file /root/cert/ip/fullchain.pem
    --reloadcmd    "systemctl restart x-ui || rc-service x-ui restart"
  ↳ 通过检查文件是否存在（而非退出码）判断成功

启用自动续期
设置文件权限
配置面板证书路径

关键特性：

• 使用 --certificate-profile shortlived 配置文件，证书有效期约 6 天
• acme.sh cron 任务会在到期前自动续期
• 不依赖退出码判断安装成功（因为 reloadcmd 失败会导致非零退出）
• 支持 IPv4 + IPv6 双栈

11. ssl_cert_issue() — 手动 SSL 证书签发（第 346-509 行）

用途：交互式域名证书签发，提供更多自定义选项。

流程：

读取当前面板的 webBasePath 和 port

检查 acme.sh（不存在则安装）

获取并验证用户输入的域名：
  └─ 循环直到输入有效域名
  └─ 检查是否已存在该域名的证书

创建证书目录：/root/cert/${domain}/

选择端口（默认 80）

临时停止面板（释放端口）

签发证书：
  acme.sh --issue -d ${domain} --listen-v6 --standalone --httpport ${WebPort}

设置 reloadcmd（证书续期后执行的命令）：
  ├─ 默认：systemctl restart x-ui || rc-service x-ui restart
  ├─ 选项 1：systemctl reload nginx ; systemctl restart x-ui
  ├─ 选项 2：自定义命令
  └─ 选项 0：保持默认

安装证书并启用自动续期

启动面板

询问是否将证书应用到面板：
  └─ 是 → x-ui cert -webCert ... -webCertKey ...
  └─ 否 → 跳过

特点：

• 签发前会停止面板以释放端口
• 支持自定义 reloadcmd（例如先 reload nginx 再重启 x-ui）
• 签发失败会自动重新启动面板

12. prompt_and_setup_ssl(panel_port, web_base_path, server_ip) — SSL 选择菜单（第 513-638 行）

用途：安装时的统一 SSL 配置入口，提供三种选择。

菜单：

1. Let's Encrypt 域名证书（90 天有效期，自动续期）
   └─ 调用 ssl_cert_issue()
   └─ 从 acme.sh 列表提取域名作为 SSL_HOST

2. Let's Encrypt IP 证书（6 天有效期，自动续期）  ← 默认选项
   └─ 可选输入 IPv6 地址
   └─ 停止面板释放 80 端口
   └─ 调用 setup_ip_certificate(server_ip, ipv6)
   └─ SSL_HOST = server_ip

3. 自定义 SSL 证书（指定已有文件路径）
   └─ 输入域名
   └─ 循环验证证书文件（存在、可读、非空）
   └─ 循环验证私钥文件（存在、可读、非空）
   └─ x-ui cert -webCert ... -webCertKey ...
   └─ 提示用户自行管理续期

全局变量：设置 SSL_HOST 供后续显示访问地址使用。

---

安装后配置

13. config_after_install() — 安装后配置（第 640-760 行）

用途：首次安装后的凭据生成、端口设置、Web 路径生成、SSL 配置。

流程图：

读取当前面板设置：
  - hasDefaultCredential（是否为默认凭据）
  - webBasePath
  - port
  - cert（证书路径）

获取服务器公网 IP：
  └─ 依次尝试 6 个 API：
     1. api4.ipify.org
     2. ipv4.icanhazip.com
     3. v4.api.ipinfo.io/ip
     4. ipv4.myexternalip.com/raw
     5. 4.ident.me
     6. check-host.net/ip

判断 webBasePath 是否足够长（≥4 字符）：

  ┌─ webBasePath 过短
  │
  │  ├─ hasDefaultCredential == true（首次安装）
  │  │   ├─ 生成随机 webBasePath（18 位）
  │  │   ├─ 生成随机用户名（10 位）
  │  │   ├─ 生成随机密码（10 位）
  │  │   ├─ 询问是否自定义端口
  │  │   │   ├─ 是 → 用户输入端口
  │  │   │   └─ 否 → 随机生成 1024-62000 范围端口
  │  │   ├─ 应用设置：x-ui setting -username ... -password ... -port ... -webBasePath ...
  │  │   ├─ prompt_and_setup_ssl()  ← 必需
  │  │   └─ 显示完整凭据和访问地址
  │  │
  │  └─ hasDefaultCredential != true（非首次安装）
  │      ├─ 生成新 webBasePath
  │      ├─ 检查是否有证书：
  │      │   ├─ 无 → prompt_and_setup_ssl()（推荐）
  │      │   └─ 有 → 显示 HTTP 访问地址
  │      └─ 结束
  │
  └─ webBasePath 正常（≥4 字符）
  
     ├─ hasDefaultCredential == true
     │   ├─ 生成随机用户名和密码
     │   ├─ 应用新凭据
     │   └─ 显示凭据
     │
     └─ hasDefaultCredential != true
         └─ 提示凭据已正确设置

     再次检查证书：
     ├─ 无证书 → prompt_and_setup_ssl()（推荐）
     └─ 有证书 → 跳过

最后执行：x-ui migrate（数据库迁移）

---

主安装逻辑

14. install_x-ui(version) — 主安装函数（第 762-958 行）

参数：$1 可选，指定安装版本号（如 v2.3.5）。

流程：

cd /usr/local/

┌─ 无版本参数（安装最新版）
│   ├─ 从 GitHub API 获取最新版本号
│   │   └─ IPv4 失败时重试 curl -4
│   └─ 下载：x-ui-linux-${arch}.tar.gz
│
└─ 有版本参数
    ├─ 验证版本号 ≥ v2.3.5
    └─ 下载指定版本

同时下载 x-ui.sh 到 /usr/bin/x-ui-temp

停止已有 x-ui 服务并删除旧安装目录

解压 tar.gz，设置执行权限

ARM 架构特殊处理：
  armv5/armv6/armv7 → 重命名为 xray-linux-arm

安装 x-ui.sh 到 /usr/bin/x-ui
创建日志目录 /var/log/x-ui/

调用 config_after_install()  ← 生成凭据 + SSL

etckeeper 兼容：
  └─ 如果 /etc/.git 存在，将 x-ui.db 加入 .gitignore

┌─ Alpine Linux
│   ├─ 下载 OpenRC 脚本 x-ui.rc → /etc/init.d/x-ui
│   ├─ rc-update add x-ui（启用开机自启）
│   └─ rc-service x-ui start
│
└─ 其他系统（systemd）
    ├─ 优先使用 tar.gz 中的服务文件
    │   ├─ x-ui.service          ← 通用
    │   ├─ x-ui.service.debian   ← Ubuntu/Debian
    │   ├─ x-ui.service.arch     ← Arch/Manjaro
    │   └─ x-ui.service.rhel     ← 其他（CentOS/Fedora 等）
    │
    ├─ 如果 tar.gz 中没有，从 GitHub 下载对应文件
    │
    └─ 配置服务：
        chown root:root x-ui.service
        chmod 644 x-ui.service
        systemctl daemon-reload
        systemctl enable x-ui
        systemctl start x-ui

显示安装完成信息和子命令用法

子命令列表（安装完成后显示）：

命令	功能
x-ui	打开管理菜单
x-ui start	启动面板
x-ui stop	停止面板
x-ui restart	重启面板
x-ui status	查看状态
x-ui settings	查看当前设置
x-ui enable	设置开机自启
x-ui disable	取消开机自启
x-ui log	查看日志
x-ui banlog	查看 Fail2ban 日志
x-ui update	更新
x-ui legacy	安装旧版本
x-ui install	安装
x-ui uninstall	卸载

---

调用关系总结

install.sh
  │
  ├─ install_base()
  │     └─ 根据发行版安装 curl, tar, tzdata, socat, ca-certificates, openssl
  │
  └─ install_x-ui($1)
        ├─ 下载 x-ui 发行版和 x-ui.sh
        ├─ 解压、设置权限
        ├─ config_after_install()
        │     ├─ gen_random_string() × 3（用户名/密码/Web路径）
        │     ├─ 获取公网 IP
        │     ├─ prompt_and_setup_ssl()
        │     │     ├─ [选项1] ssl_cert_issue()
        │     │     │     ├─ install_acme()
        │     │     │     └─ acme.sh 签发/安装/续期域名证书
        │     │     ├─ [选项2] setup_ip_certificate()
        │     │     │     ├─ install_acme()
        │     │     │     └─ acme.sh 签发/安装/续期 IP 短期证书
        │     │     └─ [选项3] 用户提供自定义证书路径
        │     └─ x-ui migrate
        └─ 配置系统服务（systemd 或 OpenRC）

---

关键设计决策

1. 强制 SSL：首次安装时必须配置 SSL 证书（三种方式选一），确保面板通过 HTTPS 访问。

2. 随机化安全：用户名、密码、端口、Web 路径全部随机生成，避免使用默认凭据。

3. 多 OS 兼容：通过 case 语句适配 7 大包管理器体系，Alpine 使用 OpenRC，其余使用 systemd。

4. IP 证书支持：利用 Let's Encrypt 的 shortlived profile，为无域名场景提供 SSL 支持（6 天有效期，自动续期）。

5. 优雅降级：

   • GitHub API 失败时用 curl -4 重试
   • ss 不可用时回退到 netstat，再回退到 lsof
   • tar.gz 中无服务文件时从 GitHub 下载
   • acme.sh reloadcmd 失败不阻止证书安装

6. etckeeper 兼容：自动将数据库文件加入 /etc/.gitignore，避免 etckeeper 追踪频繁变化的数据库。