3m-ui/docs/installation.md

安装、升级与恢复

3m-ui 提供两种完整安装方式：Linux 一键安装，以及预构建 Docker 镜像。两者均包含面板和固定版本的 Mihomo，使用相同的首次初始化逻辑。默认安装、更新及 Docker latest 只跟随稳定版。

Linux 一键安装

完整安装包支持 Linux amd64、arm64，要求 root、systemd 或 OpenRC、可访问 GitHub 的网络。不需要 Go、Node 或系统 libsqlite3。安装过程自动补齐下载和解压工具。

curl -fsSL https://raw.githubusercontent.com/kazeyukiro/3m-ui/main/scripts/install.sh | sudo sh

需要先检查脚本或指定参数时，下载到本地再执行：

curl -fsSLo install.sh https://raw.githubusercontent.com/kazeyukiro/3m-ui/main/scripts/install.sh
sudo env PANEL_PORT=8080 sh install.sh --yes

环境变量必须传给执行脚本的 sh，放在管道左侧的 curl 前面不会传递给右侧的安装程序。

首次安装默认使用 8080。放行面板和各节点实际使用的端口后，访问 http://SERVER_IP:8080/。安装时会显示管理员 admin 及随机初始密码，首次登录必须修改；遗失密码可执行 sudo 3m-ui reset-admin，生成新密码并使旧登录会话失效。密码不会写入配置文件或安装结果文件。

配置文件已存在时会保留，包括现有账号、密码、端口和密钥。重复运行安装程序用于更新程序文件，不会重置管理员。修改已安装面板的端口使用 sudo 3m-ui config port 9000。

从旧版安装脚本迁移时，先执行上面的最新安装命令一次，以安装新的快照与恢复流程；旧版 3m-ui update 不具备本文描述的完整备份保证。

HTTPS 与对外访问

首次登录改密后，在「系统设置」配置面板 HTTPS：可以申请域名证书，也可以使用已有证书。已有 Nginx / Caddy 的用户可设置面板只监听 127.0.0.1，由反向代理提供 HTTPS。域名不是安装前置要求；HTTP 端口本身不代表已启用 HTTPS。

配置证书时，将自管证书放在 /etc/3m-ui/ 或 /var/lib/3m-ui/，以便与数据库、密钥一起备份。域名解析、HTTP-01 验证所需端口、防火墙与云安全组需要与所选择的访问方式匹配。

版本与来源

v1.2.3 等标签是不可变的正式版本，v1.3.0-rc.1 是显式选择的候选版本。下列版本号仅为格式示例，请换成 Releases 中实际存在的版本。

sudo sh install.sh v1.2.3
sudo 3m-ui update v1.2.3

# 主动加入滚动测试通道；此选择会保留至后续更新。
sudo env THREE_M_UI_CHANNEL=pre 3m-ui update

# 返回稳定版更新通道。
sudo env THREE_M_UI_CHANNEL=stable 3m-ui update

没有稳定版可用时会明确失败，不会自动改装 pre。默认不会自动升级；执行更新命令时才下载目标版本。

发布自己的 fork 时，需要显式选定发行来源，例如：

sudo env THREE_M_UI_REPO=YOUR_OWNER/3m-ui sh install.sh

此来源会保存在安装目录，后续更新沿用它。Docker 使用相同发行仓库的镜像，例如 ghcr.io/YOUR_OWNER/3m-ui:v1.2.3。不能假定从 fork 下载原始脚本后，默认下载地址也会自动改变。

所有发行下载均校验 SHA256SUMS，校验失败就停止。已安装 cosign 的用户可设置 THREE_M_UI_VERIFY_COSIGN=1，额外要求工作流签名验证。

自定义内核及高级架构

完整安装默认使用 /usr/local/lib/3m-ui/mihomo，不自动复用全局 /usr/local/bin/mihomo。既有配置指定的内核路径会保留。

--no-mihomo 只安装 / 更新面板，适用于已有外部内核，或只提供独立面板二进制的其他架构。新装时可设置 THREE_M_UI_MIHOMO_BINARY=/absolute/path/to/mihomo。自定义核心需要自行验证兼容性并备份；完整发行包只承诺清单指定的配套版本。

管理与备份

sudo 3m-ui status
sudo 3m-ui version
sudo 3m-ui logs
sudo 3m-ui restart
sudo 3m-ui backup
sudo 3m-ui update

backup 会短暂停服，在 /var/lib/3m-ui/backups/ 创建完整快照，然后恢复原先的运行状态。快照包含面板程序、配套核心、管理脚本、服务定义、配置、加密密钥、数据库及其辅助文件、Mihomo 数据和证书；历史备份不会递归收入新快照。

更新先完成下载和校验，再停服建立一致快照，替换程序并执行初始化与 HTTP/HTTPS 健康检查。更新失败会尝试恢复整份快照，包括迁移前的数据库和密钥。恢复失败时会输出可用快照位置。

# 换成实际创建的绝对路径；命令会先为当前状态再做一份备份。
sudo 3m-ui restore /var/lib/3m-ui/backups/ACTUAL-SNAPSHOT.tar.gz

快照恢复要求原安装路径一致。恢复其他版本时使用对应快照，不能只换旧二进制并假定数据库能够降级。请将重要快照复制到其他机器，定期实际演练恢复。

自动快照覆盖本安装的配置与数据目录。若已配置的数据库、核心配置或证书实际位于其他共享目录，脚本会在停服前报出路径并停止，避免声称已经完成备份。先把相关存储迁入受管理目录，或自行完成相应的备份和手动更新。外部核心二进制不会被替换。

证书、核心和 ACME 目录内的文件符号链接也会检查实际目标；嵌套目录符号链接和失效链接不支持自动快照，需要先整理为受管理目录内的实际文件和目录。

sudo 3m-ui uninstall          # 保留配置、数据、密钥和证书
sudo 3m-ui uninstall --purge  # 明确确认后彻底删除本安装的持久化内容

Docker

使用本发行仓库 Releases 中的 docker-compose.yml，固定 Compose 所在目录，避免改变项目名后创建另一组空卷。

docker compose up -d
docker compose logs 3m-ui

镜像包含面板、配套 Mihomo，首次启动自动生成配置与密钥，并在日志中输出一次随机初始密码。只有密码哈希写入数据库；首次登录改密后可按自己的日志保留策略轮转首次启动日志。配置、数据和日志使用命名卷，卷权限由镜像准备。重启与容器重建不会再次生成账号或密钥。

镜像以非 root 用户运行。普通监听默认不需要 privileged 或 NET_ADMIN。低于 1024 的监听端口如受宿主机限制，可以使用高端口或为确有需要的部署添加 NET_BIND_SERVICE；TUN 等功能的权限需要自行配置。

网络与版本

默认 Compose 使用 Linux host 网络。新建监听会直接绑定宿主机端口，不需要重新创建容器，仍需处理端口冲突、防火墙和安全组。

需要 bridge 网络时，独立使用另一个模板：

docker compose -f docker-compose.bridge.yml up -d

bridge 模板仅把面板映射到 127.0.0.1:8080；公网访问需要反向代理或调整绑定。每个节点需要对应的 TCP/UDP 映射，模板包含端口范围示例。不要将 host 和 bridge 模板叠加使用。

建议在 Compose 同目录的 .env 中固定正式版本，例如：

THREE_M_UI_IMAGE=ghcr.io/kazeyukiro/3m-ui:v1.2.3

将示例换成实际发布标签。默认 latest 只跟随稳定版，pre 只用于主动参与测试。fork 的镜像仓库与发行仓库一致。

Docker 升级、备份与恢复

升级通过替换镜像完成，容器内不运行宿主机安装脚本。升级前先拉取新镜像，再停服备份持久化目录：

docker compose pull
docker compose stop
mkdir -p backups
chmod 700 backups
docker compose run --rm --no-deps --user 0 --entrypoint sh \
  -v "$PWD/backups:/backup" 3m-ui -c \
  'umask 077; tar -czf /backup/before-upgrade.tar.gz /etc/3m-ui /var/lib/3m-ui'
docker compose up -d
docker compose ps

每次使用不同备份文件名；示例中的 before-upgrade.tar.gz 会被覆盖。证书和核心配置应存放在这两个持久化目录内。记录备份对应的镜像标签或 digest；需要恢复时停服，将 .env 改回该镜像，再恢复整份快照：

docker compose stop
docker compose run --rm --no-deps --user 0 --entrypoint sh \
  -v "$PWD/backups:/backup:ro" 3m-ui -c \
  'tar -tzf /backup/before-upgrade.tar.gz >/dev/null &&
   find /etc/3m-ui /var/lib/3m-ui -mindepth 1 -maxdepth 1 -exec rm -rf {} \; &&
   tar -xzf /backup/before-upgrade.tar.gz -C /'
docker compose up -d

恢复前还应备份当前卷。上述恢复命令先验证备份可读取，再清空这两个受管理目录的现有内容，避免将旧的 WAL 等辅助文件混入恢复结果。docker compose down 保留卷，docker compose down -v 会删除持久化卷。

遗失管理员密码时：

docker compose exec 3m-ui /usr/local/bin/3m-ui reset-admin

维护发行版本

固定 Mihomo 版本、架构资产名和 SHA256 在 distribution/mihomo.env。调整此文件意味着更新配套内核，必须重新执行安装与核心兼容验证。原生完整包和 Docker 构建共用这份清单。

正式 / 候选版本工作流按标签构建，并拒绝覆盖已发布版本。滚动 pre 是独立通道。镜像发布到 ghcr.io/<当前仓库所有者>/<当前仓库名>；仓库管理员首次发布时需要确保 package 可见性适合公众拉取。

发布验证应涵盖两种架构、首次初始化、真实核心运行、登录改密、创建节点、实际代理连接、更新保留数据和快照恢复。仅编译成功不能证明一台全新服务器可以安装。