AI 指令：GitHub + Cloudflare Pages + Rust WASM + HTMX 零服务器全栈规范

本架构彻底摒弃传统的「自购 VPS + 挂常驻后台进程 + 编写冗余 JSON API」的沉重模式，建立基于全球边缘的轻量循环：

免费额度与物理红线认知

• 单次请求 CPU 时间限制：10ms。仅计算 Rust 内部实际计算消耗，等待网络 I/O 或数据库读写不扣 CPU 时间。Rust 拼接 HTML 片段耗时通常 < 0.5ms，完全胜任。严禁在 Worker 内跑大算力挖矿、长死循环或重度图像压缩。
• 动态请求量：100,000 次 / 天。每天 UTC 0 点重置，纯静态 HTML/CSS 资源走 Pages 缓存，不计入此配额。
• 无状态（Stateless）特性与数据库演进路径： 函数随用随起、执行完即销毁。严禁使用内存全局变量（如 static mut）存储业务状态，数据必须入库。
  数据库阶梯演进准则（先 D1 → 后 Supabase）：

  • 起步/轻量阶段（首选 D1 SQLite）：无需自备服务器、零配置开箱即用，每日享 500 万行读 / 10 万行写的大额免费配额，极速搞定产品闭环。
  • 扩展/企业阶段（平滑演进 Supabase Postgres）：当数据量激增、需要复杂 SQL 分析、全文索引或要求数据完全私有化时，平滑切到自建 VPS 上的 Supabase，前端 HTMX 视图层代码 0 修改。

Cloudflare 免费版限制 Worker / WASM 脚本压缩后必须小于 3 MB。Rust 默认编译会带调试符号并优先展开速度，生成文件常达数兆。AI 在初始化项目时必须按以下规约配置：

1. Cargo.toml 极限体积优化配置

[package]
name = "cf-rust-htmx-app"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
worker = "0.4"          # Cloudflare 官方 Rust SDK
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

[profile.release]
opt-level = "z"         # 极限精简文件大小（size-focused）
lto = true              # 跨 crate 链接优化，剔除所有未使用函数
codegen-units = 1       # 单编译单元，最大化优化空间
panic = "abort"         # 出错直接中止，剥离庞大的栈回溯开销
strip = true            # 剔除符号表调试信息

2. HTML 渲染选型准则

• 优先使用原生 format! 宏：无任何第三方模板依赖，编译产物仅几十 KB，速度与体积最优，适合简单的表单行、表格行、提示框。
• 复杂页面选用 maud 宏：使用 Rust 编译期宏生成类型安全 HTML，零运行时开销，杜绝 XSS 注入风险。

1. D1 核心指标与优势

D1 底层是纯正的 SQLite 引擎。享有每日 500 万行读取、10 万行写入、5 GB 存储容量的免费额度。

2. 辅助利器：什么时候用 KV？（读与写的概念释疑）

3. 标准建表规范 (schema.sql)

-- 初始表结构（以留言/任务为例）
CREATE TABLE IF NOT EXISTS items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_items_created ON items(created_at DESC);

4. Rust 操作 D1 并在边缘输出 HTML

use worker::*;

// 查询最新数据并直接组装 HTML 返回
pub async fn render_item_list(env: &Env) -> Result<Response> {
    let d1 = env.d1("DB")?;
    let statement = d1.prepare("SELECT id, title, content, created_at FROM items ORDER BY created_at DESC LIMIT 10");
    let result = statement.all().await?;
    let rows: Vec<ItemRecord> = result.results()?;

    let mut html = String::new();
    for item in rows {
        html.push_str(&format!(
            r#"<li class="list-group-item bg-dark text-light border-secondary d-flex justify-content-between align-items-center">
                <div>
                  <h6 class="mb-1">{}</h6>
                  <p class="mb-0 text-secondary small">{}</p>
                </div>
                <button class="btn btn-sm btn-outline-danger"
                        hx-delete="/api/items/{}"
                        hx-target="closest li"
                        hx-swap="outerHTML">
                  删除
                </button>
               </li>"#,
            item.title, item.content, item.id
        ));
    }

    let mut headers = Headers::new();
    headers.set("Content-Type", "text/html; charset=utf-8")?;
    Ok(Response::ok(html)?.with_headers(headers))
}

在仓库创建 .github/workflows/deploy.yml。开启 Rust 缓存加速，自动编译 WASM，并由 Pages Action 发布：

name: Build and Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install Rust Toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown

      - name: Rust Cache
        uses: Swatinem/rust-cache@v2

      - name: Install wasm-opt & worker-build
        run: |
          cargo install worker-build
          sudo apt-get update && sudo apt-get install -y binaryen

      - name: Build Rust WASM
        run: |
          worker-build --release
          # 二次优化瘦身
          wasm-opt -Oz build/worker/shim.wasm -o build/worker/shim.wasm || true

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-rust-htmx-app
          directory: dist
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

1. 极速启动极简示例模板（Bootstrap 5 + HTMX）

<!DOCTYPE html>
<html lang="zh-CN" data-bs-theme="dark">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Rust WASM + HTMX Fullstack</title>
  <link href="https://cdn.staticfile.net/bootstrap/5.3.3/css/bootstrap.min.css" rel="stylesheet">
  <link href="https://cdn.staticfile.net/bootstrap-icons/1.11.3/font/bootstrap-icons.min.css" rel="stylesheet">
</head>
<body class="py-5" style="background-color: #0a0e17; color: #e2e8f0;">
  <main class="container" style="max-width: 760px;">
    <div class="card bg-dark border-secondary p-4 mb-4 shadow">
      <h2 class="h5 text-primary mb-3"><i class="bi bi-send-fill me-2"></i>发布新记录</h2>
      <!-- 提交成功后清空表单，并将返回的 HTML 片段插入列表顶部 -->
      <form hx-post="/api/items"
            hx-target="#items-list"
            hx-swap="afterbegin"
            hx-on::after-request="if(event.detail.successful) this.reset()">
        <div class="mb-3">
          <input type="text" name="title" class="form-control bg-black text-light border-secondary" placeholder="标题" required>
        </div>
        <div class="mb-3">
          <textarea name="content" class="form-control bg-black text-light border-secondary" rows="2" placeholder="详情内容..." required></textarea>
        </div>
        <button type="submit" class="btn btn-primary">提交到 Cloudflare 边缘</button>
      </form>
    </div>

    <div class="card bg-dark border-secondary p-4 shadow">
      <h3 class="h6 text-secondary mb-3">实时记录列表</h3>
      <!-- 页面初始化自动触发加载 -->
      <ul id="items-list" class="list-group" hx-get="/api/items" hx-trigger="load">
        <div class="text-secondary small p-3 text-center">加载数据中...</div>
      </ul>
    </div>
  </main>
  <script src="https://cdn.staticfile.net/htmx/1.9.12/htmx.min.js"></script>
  <script src="https://cdn.staticfile.net/bootstrap/5.3.3/js/bootstrap.bundle.min.js"></script>
</body>
</html>

2. 如何直接套用现成 Bootstrap 5 模板（开源/商业主题）

这是 HTMX + BS5 的绝对王牌优势！传统 React/Vue 必须将现成模板重写为组件，而 HTMX 原生支持标准 HTML。你可以下载任何现成的 Bootstrap 5 后台或官网模板（如 Tabler、AdminLTE v4、SB Admin、CoreUI），通过以下四步秒变动态全栈：

1. 平滑演进：自建 Supabase (PostgreSQL) 替代 D1

当项目业务复杂，需要真正的 PostgreSQL 全文检索、外键与独立数据自主权时，可平滑对接自建 Supabase。前端 HTMX 代码 0 修改，仅在 Rust 内部将 D1 语句换为对 Supabase PostgREST 的 HTTPS 请求：

// Rust 内部请求自建 Supabase 并直接吐 HTML 片段
pub async fn fetch_from_supabase(env: &Env) -> Result<Response> {
    let base_url = env.var("SUPABASE_URL")?.to_string();
    let service_key = env.secret("SUPABASE_SERVICE_ROLE_KEY")?.to_string();

    let mut headers = Headers::new();
    headers.set("apikey", &service_key)?;
    headers.set("Authorization", &format!("Bearer {}", service_key))?;

    let req = Request::new_with_init(
        &format!("{}/rest/v1/items?select=*&order=created_at.desc&limit=10", base_url),
        RequestInit::new().with_headers(headers),
    )?;

    let mut resp = Fetch::Request(req).send().await?;
    let rows: Vec<ItemRecord> = resp.json().await?;

    // 依然直接渲染 HTML 片段给 HTMX
    let mut html = String::new();
    for item in rows {
        html.push_str(&format!(r#"<div class="p-2 border-bottom border-secondary">{}</div>"#, item.title));
    }

    let mut res_headers = Headers::new();
    res_headers.set("Content-Type", "text/html; charset=utf-8")?;
    Ok(Response::ok(html)?.with_headers(res_headers))
}

2. 公开仓库（Public）下的机密隔离铁律

• Cloudflare Pages 控制台： 进入 Settings → Environment variables 添加机密。 勾选 Encrypt（加密机密）。机密一旦保存，即使后台也无法查看明文，仅在边缘运行时以内存方式注入，物理隔离泄露。
• GitHub 仓库控制台： 进入 Settings → Secrets and variables → Actions。 仅存放部署授权令牌 CLOUDFLARE_API_TOKEN 与 CLOUDFLARE_ACCOUNT_ID，构建脚本无法向外界回显。
• 访客浏览器完全不可见： 访客在浏览器端抓包只能看到 Cloudflare 域名与 HTML 片段，真正的后端数据库 IP、域名及密钥完全隐匿在边缘层之后。