Pages on Kubernetes

一个轻量的 Cloudflare Pages 风格静态站点平台：Go 服务端、类似 Wrangler 的 pages CLI、Kubernetes 清单，以及可直接安装到 Hermes Agent 的部署 Skill。

在线示例：https://pages.renata.net.cn/

功能

• 一条命令发布静态站点：pages deploy ./dist --project my-site
• 支持纯 HTML、Vite、Vue、React、Next.js static export 等静态产物
• /p/<project>/ 路径托管和可选项目主机名
• SPA fallback
• PVC 持久化，Pod 重启后页面仍然存在
• Bearer Token 保护部署、列表和删除 API
• gzip tar 安全解包：阻止路径穿越、符号链接和硬链接
• 单次部署上限 100 MiB、10,000 个归档条目，并限制归档路径长度
• 原子替换、失败回滚以及中断部署恢复
• 用户页面使用 CSP opaque-origin sandbox
• 非 root、只读根文件系统、RuntimeDefault seccomp、禁用 ServiceAccount Token
• 无公开管理后台，管理操作统一通过 CLI 完成

快速开始

构建

make test
make build VERSION=v0.1.5

产物：

bin/pages
bin/pages-server-linux-amd64

安装 CLI：

install -m 755 bin/pages ~/bin/pages

配置 CLI

推荐通过 HTTPS：

pages configure \
  --server https://pages.example.com \
  --token '<API token>'

也支持 SSH 隧道模式：

pages configure \
  --server http://SERVER-IP:30100 \
  --token '<API token>' \
  --ssh user@SERVER-IP

配置文件权限为 0600。CLI 会拒绝把 Bearer Token 发送到远程明文 HTTP；只有 HTTPS 或实际建立后的 loopback SSH 隧道可以发送认证请求。

发布页面

pages deploy ./dist --project my-site
pages projects
pages delete my-site

项目名只能包含小写字母、数字和连字符，最长 63 个字符。发布目录根部必须包含 index.html。

Kubernetes 部署

清单位于 deploy/kubernetes.yaml。部署前：

1. 修改镜像地址、StorageClass 和 namespace；
2. 单独创建 API Token Secret，不要提交真实 Token；
3. 如使用私有镜像仓库，创建 registry-secret；
4. 如 HTTPS 在反向代理终止，只将代理的实际来源 IP加入 PAGES_TRUSTED_PROXY_IPS。

kubectl -n apps create secret generic pages-api \
  --from-literal=token="$(openssl rand -hex 32)"

kubectl apply -f deploy/kubernetes.yaml
kubectl -n apps rollout status deployment/pages

PAGES_TRUSTED_PROXY_IPS 是逗号分隔的 IP 列表。服务端只接受这些可信来源设置的 X-Forwarded-Proto: https；不要配置过宽的网段或用户可直接伪造的来源地址。

Hermes Agent Skill

仓库包含 skills/frontend-pages-deployment/SKILL.md，用于自动执行：

1. 检测前端构建目录；
2. 检查根目录 index.html；
3. 运行 pages deploy；
4. 通过 HTTP 获取线上页面并验证标记；
5. 返回真实可访问 URL。

安装到当前 Hermes profile 的 software-development 分类：

HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/skills/software-development"
cp -R skills/frontend-pages-deployment \
  "$HERMES_HOME/skills/software-development/"

默认 profile 通常使用 HERMES_HOME=~/.hermes。其他 profile 请复制到对应 profile 的 skills/software-development/ 目录，然后执行 /reload-skills 或新建会话。

开发与测试

go test -race ./...
go vet ./...
git diff --check

项目结构

cmd/pages/             CLI
cmd/pages-server/      HTTP 服务入口
internal/archive/      安全归档解包
internal/client/       CLI API 客户端
internal/server/       Pages API 与静态文件服务
deploy/                Kubernetes 清单
skills/                Hermes Agent 部署 Skill
sites/                  示例静态页面

License

MIT