让任何一键安装脚本在国内全速跑：一份可复用的镜像改造提示词

国内机器运行一键安装脚本时，最常见的失败方式是长时间无响应。多数情况下不打印任何报错：

curl -fsSL https://raw.githubusercontent.com/.../install.sh -o install.sh
^C

脚本本身可以正常执行。它引用的下载地址大多位于中国大陆以外。我按同一套方法改了两个脚本：Komari 只依赖 GitHub，Plane 还依赖 Docker Hub。下面记录改造方式、过程中出现的问题，以及可以直接复制的提示词。

三类境外依赖

一键安装脚本访问的境外地址分三类：

类型	典型地址	体积	手段
GitHub	`api.github.com`、`github.com/*/releases`、`raw.githubusercontent.com`、`git clone`	几 KB ~ 几十 MB	反代镜像前缀，失败换源
容器镜像	`docker.io`、`ghcr.io`	几百 MB ~ 几 GB	registry 镜像站，改写镜像名
包管理器	apt / yum / npm / pip / go	几 MB ~ 几百 MB	换源（通常机器上已配好）

GitHub 与容器镜像需要分开处理。GitHub 地址增加镜像前缀即可；容器镜像需要改写镜像名，并处理认证与可用性探测。只处理 GitHub 的做法，在 Plane 这类脚本上仍会卡在 docker compose pull。

提示词

以下内容可以直接交给 AI，把脚本内容或链接替换掉 <脚本>：

你是一名熟悉国内网络环境的运维工程师。下面是一个一键安装脚本：<脚本>

目标：不改变脚本的功能、交互菜单、服务配置、升级/卸载逻辑，只替换「取文件」的部分。

1. 找出脚本里所有访问境外地址的地方，按三类分组列出：GitHub / 容器镜像 / 包管理器。
2. GitHub 请求改成「镜像链」：默认 https://ghfast.top https://gh-proxy.com https://ghproxy.net，
   按顺序尝试，失败自动换下一个，全部失败再回落直连；支持环境变量覆盖镜像列表与是否允许直连。
3. 注意镜像能力差异：不是所有镜像都代理 api.github.com。API 取不到时用 releases.atom 兜底，
   不要直接判定「获取版本失败」。
4. 二进制下载必须校验：优先用 GitHub 官方 release 公布的 sha256 digest；
   取不到摘要时，至少检查文件头是不是 ELF（7f454c46），防止把镜像返回的 HTML 错误页当成程序装上。
   校验失败要丢弃并换下一个源，绝不允许带着坏文件继续安装。
5. Docker 镜像不要把地址硬编码：运行时用 docker manifest inspect 探测哪个镜像站可用，
   把 compose 里的 image 改写成 <镜像站>/<仓库>:<tag>，官方镜像要补 library/ 前缀；
   拉取失败自动还原成官方镜像名重试一次。不要修改 /etc/docker/daemon.json，不要影响机器上其他项目。
6. 所有新行为都要能通过环境变量覆盖（镜像列表、是否允许直连、是否强制校验、是否禁用镜像）。
7. 交付前必须给出：bash -n、与原版对比的 shellcheck、函数级测试（地址拼接/换源/改写/回滚）、
   以及一次真实下载的端到端验证结果（含校验值比对）。
8. 没能在你环境里验证的部分，必须明确标注出来，不要说过头。

这份提示词写明判断条件：成功标准、失败后的降级顺序、校验不通过时的处理、不允许改动的范围。缺少这些条件时，生成结果通常只是一批 sed 替换，运行时仍然卡住。

实战一：Komari（只有 GitHub）

原脚本访问三个地址：

https://api.github.com/repos/<repo>/releases          # 找快照版
https://github.com/<repo>/releases/latest/download/…  # 正式版二进制
https://github.com/<repo>/releases/download/<tag>/…   # 快照版二进制

改造后的下载日志：

GitHub 镜像：https://ghfast.top https://gh-proxy.com https://ghproxy.net
正在尝试源：https://ghfast.top/https://github.com/komari-monitor/komari/releases/...
正在下载 komari 100% [########################] 27.3 MiB / 27.3 MiB
SHA-256 已与官方发布摘要核对通过。

该文件大小 27.3 MiB（28,620,584 字节）。改造后下载的文件，sha256 与 GitHub 官方公布的 3deeb560…c118c739e 一致。

镜像测速（同一台机器）：

镜像	取 2 KB 耗时	说明
`gh-proxy.com`	~1.1 s	同时支持 release 与 api.github.com
`ghfast.top`	~1.4 s	只支持 release 下载，api 返回 403
`ghproxy.net`	8–16 s	可用但慢
其余若干常见镜像	超时 / 只返回落地页	已经无法使用

最后一行说明同一镜像站对不同仓库的授权策略不同：官方基础镜像可匿名拉取，第三方仓库要求登录。测试应使用实际要拉取的镜像；探 /v2/ 返回 401 只表示服务可达。

实战二：Plane（GitHub + Docker Hub）

Plane 的 setup.sh 只有两个文件走 GitHub（docker-compose.yml 与 variables.env，合计不到 10 KB），主要部分是 13 个容器镜像：

makeplane/plane-frontend / plane-space / plane-admin / plane-live
makeplane/plane-backend ×4 / plane-proxy
postgres:15.7-alpine / valkey/valkey / rabbitmq
pgsty/silo:RELEASE-…

处理方式是在安装时探测并改写 compose，不改动全局 docker 镜像加速配置：

按候选列表用 docker manifest inspect <镜像站>/makeplane/plane-proxy:<版本> 实测；
把 compose 中 13 个 image: 改写成 <镜像站>/<仓库>:<tag>，官方镜像补 library/；
拉取失败时还原为官方镜像名重试一次；
原始 compose 备份为 .hub.bak，可以随时回滚。

这样只改项目目录，不改 /etc/docker/daemon.json，不影响机器上运行的其他项目。

实测镜像可用性（针对 Plane 的实际镜像）：

镜像站	`makeplane/plane-proxy:v1.4.3`	`library/postgres`
`docker.1ms.run`	200	200
`docker.1panel.live`	200	200
`docker.m.daocloud.io`	403	200

docker.m.daocloud.io 对 makeplane/plane-proxy 返回 403，对 library/postgres 返回 200。测试需要使用实际要拉取的镜像。/v2/ 返回 401 只说明服务可达。

过程中遇到的问题

1. 镜像站会改变 JSON 排版

GitHub API 返回紧凑 JSON，gh-proxy.com 会重新缩进：

"name": "komari-linux-amd64",
...
"digest": "sha256:3deeb560..."

第一版解析器按 "name":"…"（无空格）匹配，在重新缩进后的输出中取不到摘要，校验被跳过，且没有任何输出。下载照常成功，日志也不报错。解析后增加一条断言（摘要长度必须为 64），这个缺陷得以暴露。

修法是先按逗号切分，再逐行匹配，两种排版都可以解析。结论：静默降级属于缺陷，降级时应当输出原因。

2. 命令替换在子 shell 中执行

local url
if ! url=$(get_download_url "$arch"); then   # 子 shell
    ...
fi
# get_download_url 里设置的 ASSET_NAME / RELEASE_TAG 在这里是空的

校验需要资产名与 tag，取到空字符串时校验被跳过。改为从 URL 反推：basename 得到资产名，正则取出 /download/<tag>/，不再依赖跨进程状态。

原版还有一处问题：快照版的 tag 用 sed 's/.*"tag_name"...//' 提取，贪婪匹配在紧凑 JSON 下会取到列表中的最后一个 tag，安装的可能是较旧的版本。改为逐字段提取后正常。

3. 命令失败不等于资源不存在

原版 Plane 脚本中有这样一段：

docker manifest inspect "makeplane/plane-proxy:$VERSION" | grep -q "\"architecture\": \"$ARCH\""

网络不通时该命令失败，脚本判定「该架构镜像不存在」，随后引导本地构建镜像，在国内外条件下耗时数小时。改法：docker manifest inspect 取不到清单时输出警告并继续尝试拉取；只有在取得清单且架构不匹配时提示本地构建。

4. 证书错误与限流会被折叠成失败

curl -f 把 403、429、502 都当作失败，日志中只显示「所有源都不可用」。排查时保留一个可以打印 HTTP 状态码的探测脚本，可以区分证书错误、限流和 404。

5. 修改 UTF-8 脚本时避免使用 PowerShell

用 Set-Content 修改带中文注释的脚本时，编码按 GBK 重写，中文变成乱码，并且吞掉了一个引号，脚本出现语法错误。修改这类文件应使用能保证 UTF-8 的编辑器或工具。

验收

两个脚本的验收项目：

检查	方式	结果
语法	`bash -n`	通过
静态检查	与原版对比 shellcheck 告警数	Komari 5 vs 原版 8；Plane 16 vs 原版 17
逻辑单测	地址拼接 / 换源顺序 / 改写 / 回滚 / 特殊写法	全过
环境探测	无 Docker、坏镜像、全源不可用	均安全降级
端到端	真实下载 28 MB 并比对官方 sha256	一致
干跑	`COMPOSE_CMD=echo` 跑完整安装流程	compose/env/镜像名/备份全部正确

「坏镜像」一项需要构造：把镜像列表第一项写成一个不存在的域名，确认脚本失败后切换到第二个源继续执行。

边界

镜像不是官方源。SHA-256 校验可以拦截错误页、截断文件与被替换的二进制，但摘要本身也通过镜像获取，信任链没有实质提升。需要严格校验时，摘要应从可信出口获取。
镜像会失效。2024 年以来大量公共镜像关停，今天可用的列表，几个月后可能大部分不可用。脚本应在运行时探测并支持退化，不能假定某个镜像长期可用。
镜像不能替代认证。私有仓库与需要 docker login 的资源，换镜像同样不可用。
不要修改系统级配置。修改 daemon.json 影响整机；修改项目自身的 compose 影响范围可控，出问题可以回滚。

小结

一键脚本在国内无法跑通，多数情况源于脚本假定所有下载地址可达。把这些假设改为「探测 → 换源 → 校验 → 降级」的处理流程，并定义明确的失败边界，脚本就可以正常执行。

两个改造后的脚本：Komari 的 install-komari-cn.sh（约 1600 行，GitHub 镜像 + 官方 SHA-256 校验）、Plane 的 plane-setup-cn.sh（约 830 行，额外处理 Docker registry 探测与 compose 改写）。