自托管 lavish-axi 分享后端：Cloudflare Worker 参考实现与 API 契约指南

自托管 lavish-axi 分享后端Cloudflare Worker 参考实现与 API 契约指南【免费下载链接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.项目地址: https://gitcode.com/gh_mirrors/la/lavish-axilavish-axi是一个本地优先的 HTML 工件编辑器它的lavish-axi share命令默认把 HTML 发布到第三方托管服务 ht-ml.app。如果你希望分享页面完全托管在自己可控的服务器上——数据不出内网、域名自己说了算——本文带你完整走一遍官方 API 契约长什么样、一个环境变量如何切换到自己的后端、以及官方文档里给出的 Cloudflare Worker 参考实现到底解决了哪些问题。一、先搞懂 share 命令在做什么 在执行lavish-axi share html-file时CLI 会做三件事打包把 HTML 里的本地图片、CSS、脚本内联进单个文件远程 CDN 引用保持原样逻辑与export完全一致见 src/export-bundle.js发布把整页 HTML 以 JSON 形式POST到分享后端默认目标是 ht-ml.app回执后端返回访问 URL 和一个只显示一次的秘密update_key它是日后更新、锁页、撤稿的唯一凭据。发布出来的 HTML 可以携带图表、白板和交互动画——比如下面这个带 Mermaid 流程图和会话面板的工件右侧面板可以直接向 Agent 发送修改意见整个发布通道的源码在 src/html-app.js测试在 test/html-app.test.js行为边界都写得清清楚楚。二、API 契约只有 2 个端点 官方契约文档是 docs/self-hosting-share.md你的后端只需要实现两个接口两个请求都在 30 秒超时内完成操作端点认证方式创建页面POST /v1/sitesAuthorization: Bearer token仅当你配置了 token重新发布 / 撤稿PUT /v1/sites/{site_id}Authorization: Bearer update_key创建请求的 body 很简单{ html_content: 完整的内联 HTML, password: 可选--private 或 --password 时携带 }响应必须至少包含url和update_key缺失任一个share命令都会直接报错{ url: https://plans.example.com/abc123, update_key: 秘密只显示一次, site_id: abc123, status: published }几个容易踩的契约细节site_id会拼进 URL 路径所以只能取A-Za-z0-9._-字符集全点的 id 会被拒绝重新发布用update_key认证不认创建时的 token--token在重发时会被显式拒绝密码无法删除——password缺省时保留原密码提供时设置或轮换永远不要回传空字符串没有 DELETE--unpublish实际是一次PUT用占位页替换原内容并锁上一个随机密码。三、一个环境变量切换到自己的后端 ⚙️配置只有两个变量定义见 docs/self-hosting-share.md#L7-L12环境变量作用LAVISH_AXI_HTML_APP_API_URL你的分享后端 Base URL默认https://api.ht-ml.app结尾斜杠会被自动去掉LAVISH_AXI_HTML_APP_TOKEN可选 Bearer token仅用于POST /v1/sites也可用--token按次传入设置示例export LAVISH_AXI_HTML_APP_API_URLhttps://share-api.your-domain.com export LAVISH_AXI_HTML_APP_TOKENs3cret-token lavish-axi share plan.html就这么简单——CLI 侧零改动所有 URL 拼接、update_key校验、不完整响应检测都由 src/html-app.js 统一处理。四、Cloudflare Worker 参考实现 官方文档内置了一份最小可用的 Workerdocs/self-hosting-share.md#L83-L124核心逻辑压缩后如下export default { async fetch(req, env) { const { pathname } new URL(req.url); const bearer (req.headers.get(authorization) || ).replace(/^Bearer /, ); // 创建必须校验 token否则任何人都能在你的域名上托管任意 HTML if (req.method POST pathname /v1/sites) { if (bearer ! env.SHARE_TOKEN) return new Response(Unauthorized, { status: 401 }); const { html_content, password } await req.json(); const id crypto.randomUUID().slice(0, 8); const update_key crypto.randomUUID(); await env.SITES.put(id, JSON.stringify({ html_content, password: password || null, update_key })); return Response.json({ url: https://${env.VIEW_HOST}/${id}, update_key, site_id: id, status: published }); } // 重发 / 撤稿update_key 是页面唯一凭据不匹配必须 401绝不静默忽略 const site pathname.startsWith(/v1/sites/) pathname.slice(/v1/sites/.length); if (req.method PUT site !site.includes(/)) { const stored await env.SITES.get(site, json); if (!stored || bearer ! stored.update_key) return new Response(Unauthorized, { status: 401 }); const { html_content, password } await req.json(); await env.SITES.put(site, JSON.stringify({ ...stored, html_content, password: password || stored.password })); return Response.json({ url: https://${env.VIEW_HOST}/${site}, site_id: site, status: published }); } return new Response(Not found, { status: 404 }); }, };配套只需三件事在 KVSITES里存{html_content, password, update_key}配置VIEW_HOST环境变量作为访问域名前缀把查看器GET /:id部署在独立域名并在返回 HTML 前强制执行存储的password。五、安全清单3 条铁律 用 token 守住POST /v1/sites——未鉴权的创建端点等于允许任何人挂钓鱼页面到你的域名下隔离查看器来源——发布的工件自带 JavaScript务必跑在专用域名 严格 CSP 下别让它摸到你主站的 Cookie尊重password字段——存在密码的页面必须先验证密码再吐出 HTML。另外两个行为提醒页面从公开变为私有不是瞬时的CDN 缓存可能继续放几分钟而update_key只返回一次丢了这页就再也没法更新——参考实现的crypto.randomUUID()正是为此而生。六、延伸阅读 资料路径自托管完整契约docs/self-hosting-share.md发布/更新传输层源码src/html-app.js分享密码生成防误输字符集src/share-password.jsshare 命令实现src/cli.js想动手试的话先克隆仓库读一遍契约文档再按 Worker 参考实现部署一个最小心跳服务用LAVISH_AXI_HTML_APP_API_URL指过去一条lavish-axi share就能验证整条链路。【免费下载链接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.项目地址: https://gitcode.com/gh_mirrors/la/lavish-axi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考