快速部署 kage Docker 镜像：离线镜像站一键搭建与 Chrome 路径自定义配置指南

快速部署 kage Docker 镜像：离线镜像站一键搭建与 Chrome 路径自定义配置指南

【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kage

kage（影）是一款用真实无头 Chrome 渲染网页、剥离全部 JavaScript后把整站克隆为可离线浏览文件的镜像工具。通过官方 Docker 镜像，你无需在宿主机安装 Chrome，一条命令即可搭好离线镜像站；配合KAGE_CHROME环境变量与--chrome参数，还能精确控制 kage 使用哪个 Chrome 二进制。本文面向新手，完整讲解 kage Docker 部署流程与 Chrome 路径自定义配置方法。

🐳 为什么用 Docker 部署 kage？

kage 的核心流程是：种子 URL → 无头 Chrome 渲染 → 快照最终 DOM → 剔除脚本 → 资产本地化 → 落盘。这意味着它必须有一个可用的 Chrome/Chromium。直接安装时需要你自行解决浏览器依赖，而官方容器镜像把这些全部打包好了：

镜像定义见 Dockerfile，构建时通过 GoReleaser 用 buildx 打包多平台版本，并把已交叉编译好的静态二进制直接COPY进镜像，构建很快。

🚀 Docker 镜像部署：一条命令搞定

部署的关键是一个挂载卷——容器把工作目录和HOME都指向/out，所以只要把宿主机的目录挂到/out，镜像产物就直接落在你本地：

docker run -v "$PWD/out:/out" ghcr.io/tamnd/kage clone paulgraham.com

运行结束后，镜像文件位于宿主机的./out/paulgraham.com/，里面是可离线打开的.html页面、本地化的 CSS/图片/字体，以及记录断点状态的_kage/state.json（布局详见 docs/content/reference/configuration.md）。

几个新手常踩的点：

• 镜像文件落盘位置：容器内默认输出根是$HOME/data/kage，而 Dockerfile 已把HOME设为/out，因此产物统一出现在挂载卷里，不会"藏"在容器内部。
• 为什么容器以 root 运行：这是有意为之。宿主机绑定的/out属主随环境变化，只有 root 能可靠写入；若不可写，不仅克隆失败，Chrome 还会因崩溃数据库路径为空而整体启动失败。容器内 Chrome 沙箱本就会被自动关闭，所以 root 不会带来额外风险（详见 Dockerfile 注释）。
• 可断点续爬：kage 的抓取是幂等的，中断后重跑会读取_kage/state.json跳过已完成页面。若只是想一次性跑完不留状态，可加--no-resume。

进阶用法：定期刷新镜像

配合--refresh让旧镜像原地重渲染、抓到网站更新，非常适合放进定时任务：

# 每周刷新一次离线镜像 30 3 * * 0 docker run -v /srv/mirror:/out ghcr.io/tamnd/kage clone example.com --refresh

想给大站做范围控制（只抓某个栏目、限制页数和深度），推荐先看 docs/content/guides/scoping-a-crawl.md。

🎯 kage 的 Chrome 路径是怎么找的？

kage 启动浏览器时的查找顺序是固定的（实现见 browser/pool.go）：

1. --chrome命令行参数（优先级最高）
2. KAGE_CHROME环境变量
3. CHROME_BIN环境变量
4. 内置查找器 + 各平台常见安装路径

各平台自动探测的默认路径：

如果以上都没找到，kage 的启动器可以在首次使用时自动下载一份私有 Chromium——但生产环境还是建议显式指定路径，行为更可控。

🔧 自定义 Chrome 路径配置：三种方式

环境变量参考见 docs/content/reference/configuration.md。

方式一：--chrome参数（一次性指定）

kage clone example.com --chrome /path/to/chromium

方式二：KAGE_CHROME环境变量（推荐，全局生效）

export KAGE_CHROME=/opt/chrome/chrome

方式三：CHROME_BIN回退变量

KAGE_CHROME未设置时读取它，常与其他工具共用的场景很方便。

在 Docker 场景里，Dockerfile 已经替你设置好了KAGE_CHROME=/usr/bin/chromium-browser，指向镜像内置 Chromium，所以容器内无需任何额外配置；如果你要构建自定义镜像（比如换更高版本 Chromium 或加字体），只要保证新路径与KAGE_CHROME一致即可。

✅ 部署后如何验证离线镜像

1. 在宿主机执行kage serve out/paulgraham.com，浏览器打开http://127.0.0.1:8800；
2. 页面应能正常点击跳转、加载本地图片与样式，且完全不需要外网；
3. 抽查任意.html文件，确认没有<script>标签、onclick或javascript:链接——这正是 kage 的核心价值：你拿到的是渲染完成后的最终画面，而不是一个试图联网的"薄客户端"。

📦 总结

从docker run到离线可读的整站镜像只需要一条命令，而 Chrome 路径的三级配置（参数 → 环境变量 → 自动探测）让你在任何环境下都能让 kage 精确使用你想用的浏览器。需要源码级细节时，可参考 browser/pool.go 的启动器实现与 Dockerfile 的镜像构建说明。

【免费下载链接】kageShadow any website for offline viewing, with the JavaScript stripped out项目地址: https://gitcode.com/gh_mirrors/kage6/kage