Audlis Docs

Appearance

1. 文档目的 ​

本文用于说明 Audlis 当前基于 Cloudflare 的技术架构，包括：

  • 运行时选型
  • 请求流转方式
  • 数据与存储层职责
  • 后台与前台的部署模型
  • 第三方服务集成方式
  • 当前架构的优势、边界与后续演进方向

这份文档服务于研发理解、运维排查、书稿写作和架构复盘。

2. 架构目标 ​

Audlis 选择 Cloudflare，不是为了“追求新”，而是为了满足跨境电商系统的几个现实要求：

  • 前台页面需要全球访问速度
  • 后台和 API 需要一体化部署
  • SSR、支付回调、订单查询、客服接口需要同一套应用层
  • 成本需要可控
  • 不希望拆成多套松散系统

因此，Audlis 当前采用的是：

Cloudflare Pages + Functions SSR + D1 + 定时任务 / 外部服务集成 的一体化边缘全栈模式

3. 当前核心组件 ​

3.1 Cloudflare Pages ​

职责：

  • 承载站点部署
  • 对外提供前台页面与后台页面
  • 承载 Astro SSR 输出

对应特点：

  • 前台和后台共享同一应用代码库
  • 不需要单独维护前端静态站和 API 服务两套部署链路

3.2 Cloudflare Functions ​

职责：

  • 承载所有服务端页面渲染逻辑
  • 承载 API 路由
  • 提供 session、鉴权、订单处理、供应商集成、AI 调用等服务端能力

Audlis 中的主要服务端能力均位于 src/pages/api/*，并运行在 Cloudflare Functions 上。

3.3 Cloudflare D1 ​

职责：

  • 保存商品、订单、用户、营销、客服、物流、隐私请求等业务数据

当前 D1 已覆盖的核心数据域包括：

  • 商品与分类
  • 用户与 session 相关数据
  • 订单与订单项
  • 物流事件与异常
  • 客服会话与工单
  • 隐私请求
  • 营销文案、营销资产、渠道包、生成记录
  • 应用配置 app_config

3.4 定时任务 / Cron Worker ​

职责：

  • 承载周期性任务
  • 如物流同步、生命周期营销触发、未来的自动清理与通知任务

项目中已有 cron-worker/index.ts 与 wrangler.cron.toml，用于延展后台事件驱动能力。

3.5 第三方服务 ​

Audlis 当前通过服务端集成以下关键第三方：

  • Stripe：支付与 webhook
  • CJ Dropshipping：供应商与履约
  • AI 提供商：商品编辑、营销文案、图片 / 视频生成
  • Unsplash：营销素材参考图库
  • 邮件服务（Resend 等）：生命周期邮件与验证邮件

4. 应用层结构 ​

4.1 前台 ​

前台主要由 Astro 页面和少量交互组件组成，特点是：

  • 商品页、结账页、订单页等使用 SSR
  • 局部交互由 Preact 组件承担
  • 统一布局、统一 header/footer、统一语言切换

典型页面：

  • /
  • /shop
  • /products/[slug]
  • /cart
  • /checkout
  • /orders
  • /account

4.2 后台 ​

后台与前台在同一站点内，但有独立工作区：

  • /admin

后台特点：

  • SSR 输出后台工作台
  • 主要操作通过前端组件 + 同域 API 完成
  • 无需单独开一套管理端服务

主要后台模块包括：

  • Products
  • Orders
  • Supplier Imports
  • Support
  • Logistics
  • Privacy
  • Marketing
  • Settings

4.3 API 层 ​

API 按职责拆分为：

  • 用户侧 API：/api/user/*
  • 订单 / 结账 / 支付 API
  • 后台 API：/api/admin/*
  • 客服 API：/api/support/*
  • webhook API：/api/webhooks/*

这样做的好处是边界清晰，权限模型也更明确。

5. 请求流转说明 ​

5.1 前台页面请求 ​

流程：

  1. 用户访问页面
  2. Cloudflare Pages 接收请求
  3. Functions SSR 渲染 Astro 页面
  4. 页面服务端直接从 D1 读取必要数据
  5. HTML 返回给用户

适合的数据：

  • 商品详情
  • 分类展示
  • SEO 相关信息
  • 初始营销 landing 配置

5.2 前台交互请求 ​

流程：

  1. 用户在浏览器触发交互
  2. 前端组件请求同域 /api/*
  3. Functions 在服务端执行业务逻辑
  4. 写入 D1 或调用第三方
  5. 返回 JSON

典型例子：

  • 加入购物车后的结账
  • 订单查询
  • 用户资料更新
  • AI 客服消息

5.3 后台操作请求 ​

流程：

  1. 管理员在 /admin 工作台操作
  2. 组件请求 /api/admin/*
  3. session / admin 权限校验
  4. 读写 D1 或调用外部供应商 / AI 服务
  5. 返回后台数据

典型例子：

  • 商品编辑
  • 供应商导入
  • 物流异常查看
  • 营销文案 / 资产生成

5.4 支付回调 ​

流程：

  1. 用户通过 Stripe 完成支付
  2. Stripe 调用 /api/webhooks/stripe
  3. 系统在服务端校验签名
  4. 更新订单状态
  5. 触发后续履约逻辑

这里 webhook 是支付事实源，前端返回页不是最终权威状态。

6. 数据分层 ​

Audlis 当前大致可分为 6 个数据域：

6.1 Catalog ​

  • products
  • categories
  • variants
  • specs
  • images
  • source_data

6.2 Commerce ​

  • carts（浏览器侧）
  • orders
  • order_items
  • discounts
  • payment status

6.3 Operations ​

  • supplier config
  • tracking events
  • shipping exceptions
  • return / review / inquiry 数据

6.4 Customer ​

  • users
  • profiles
  • addresses
  • account settings

6.5 Compliance ​

  • privacy requests
  • deletion / export / correction records

6.6 Growth ​

  • marketing_copy_variants
  • marketing_assets
  • marketing_campaign_packs
  • marketing_generation_runs
  • marketing landing config

7. 配置管理策略 ​

当前配置分三层：

7.1 Cloudflare secret / env ​

用于：

  • Stripe secret
  • AI API key
  • Resend key
  • Unsplash access key
  • 供应商 API key

特点：

  • 不进入仓库
  • 适合敏感配置

7.2 app_config ​

用于：

  • 非敏感后台设置
  • 供应商 token 缓存
  • AI 模型选择
  • 社媒链接
  • 营销与站点配置

特点：

  • 可由后台直接维护
  • 是系统级动态配置层

7.3 页面级 / 商品级配置 ​

如：

  • source_data
  • marketingLanding

这类配置直接与商品或页面消费逻辑相关。

8. AI 能力在 Cloudflare 架构中的位置 ​

AI 不是独立服务，而是当前应用的服务端扩展能力。

运行方式：

  • 用户 / 管理员在前台或后台触发 AI 动作
  • Functions API 组装 prompt 和输入
  • 调用第三方模型服务
  • 结果写回 D1
  • 前台 / 后台页面消费结果

这样做的好处：

  • 权限和数据都在自己系统里
  • 可做版本记录
  • 可把 AI 输出与商品、订单、营销资产绑定

9. Cloudflare 架构的主要优势 ​

9.1 一体化 ​

前台、后台、API、SSR、数据层、部署都在一套工程和平台内，减少了系统碎片化。

9.2 全球访问性能 ​

对于跨境电商，商品展示和营销落地页的访问速度很关键，Cloudflare 在这一点上天然有优势。

9.3 成本结构适合中小团队 ​

在项目仍处于增长和迭代阶段时，Cloudflare 的成本结构比自建多服务集群更友好。

9.4 适合事件驱动 ​

订单、物流、客服、AI 生成、生命周期邮件这类能力，本质上都适合事件驱动架构。

10. 当前架构的边界与风险 ​

10.1 D1 本地 / 远端一致性 ​

当前项目已经多次暴露一个现实问题：

  • 远端迁移执行了
  • 本地 dev 数据库没同步
  • 结果是后台页面或 API 缺表 / 缺列报错

所以 D1 虽然足够适合当前阶段，但迁移纪律必须严格执行。

10.2 配置来源可能分散 ​

env、secret、app_config、商品级 source_data 并存时，如果文档和设置页没有收口，就会导致排查困难。

10.3 第三方服务边界 ​

AI、支付、供应商、邮件都不在 Cloudflare 内部，Cloudflare 负责的是：

  • 承接服务端逻辑
  • 组织调用
  • 落库与消费

并不能替代第三方服务本身的稳定性和规则变化。

10.4 后台复杂度持续增长 ​

随着营销中心、客服、物流、合规等功能增加，后台已经接近一个中台系统，而不再只是 CRUD 面板。

这意味着：

  • 信息架构要持续治理
  • 设置项要分组
  • 文档必须同步

11. 当前最适合的演进方向 ​

从架构角度看，Audlis 接下来最合理的演进是：

11.1 继续保持 Cloudflare 一体化 ​

前台、后台、API、营销中心、客服、物流、合规，继续保留在一个统一系统内。

11.2 对高复杂度能力做边界分层 ​

例如：

  • 营销内容生产留在系统内
  • 广告投放执行留在系统外

11.3 强化事件与观测能力 ​

包括：

  • 实验事件
  • 生命周期事件
  • 物流异常事件
  • AI 生成失败监控

11.4 强化迁移与配置治理 ​

这是当前最现实、最容易踩坑的基础工程问题。

12. 一句话总结 ​

Audlis 当前的 Cloudflare 架构不是“为了上 Cloudflare 而上”，而是因为：

对一个正在从交易站点演进为运营与增长系统的跨境电商项目来说，Cloudflare 提供了一种足够轻、足够快、足够统一的全栈落地方式。

后续如果要写成书，这份架构说明就是“为什么选择 Cloudflare，以及它如何支撑真实电商系统”的基础章节素材。

Synergy Books · SYS-BOOK Series

Copyright © 2026 yunyi yan