Skip to content

Commit e18d4bc

Browse files
CopilotNewFuture
Copilot
and
NewFuture
authored
docs: add ESA Pages and Edge Function deployment guide (#659)
* Initial plan * docs: add ESA Pages and Function deployment guide - Created comprehensive Chinese documentation (esa-deploy.md) - Added navigation entries in VitePress config - Added sidebar entries for both Chinese and English - Documented deployment steps, configuration, and troubleshooting Co-authored-by: NewFuture <6290356+NewFuture@users.noreply.github.com> * docs: remove unnecessary sections from ESA deploy guide - Removed "构建缓存" and "预览环境" sections - Removed "监控指标" section - Removed entire "故障排除" section - Removed "优化建议" section Simplified the documentation based on feedback to focus on essential deployment information. Co-authored-by: NewFuture <6290356+NewFuture@users.noreply.github.com> * add esa * update links --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: NewFuture <6290356+NewFuture@users.noreply.github.com> Co-authored-by: New Future <NewFuture@users.noreply.github.com>
1 parent 889593a commit e18d4bc

3 files changed

Lines changed: 320 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,3 +281,7 @@ Docker 镜像在无额外参数的情况下，已默认启用每 5 分钟执行
281281
- [ ] 源码运行注明使用的 python 环境
282282

283283
</details>
284+
285+
## 服务赞助
286+
287+
![esa](https://edge-ddns-proxy.newfuture.cc/images/esa.png)

‎docs/.vitepress/config.mts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,8 @@ export default defineConfig({
127127
text: '开发文档',
128128
items: [
129129
{ text: '配置文档', link: '/dev/config' },
130-
{ text: 'Provider开发', link: '/dev/provider' }
130+
{ text: 'Provider开发', link: '/dev/provider' },
131+
{ text: 'ESA Pages部署', link: '/esa-deploy' }
131132
]
132133
}
133134
],
@@ -173,6 +174,12 @@ export default defineConfig({
173174
{ text: '配置文档', link: '/dev/config' },
174175
{ text: 'Provider开发指南', link: '/dev/provider' }
175176
]
177+
},
178+
{
179+
text: '部署文档',
180+
items: [
181+
{ text: 'ESA Pages部署', link: '/esa-deploy' }
182+
]
176183
}
177184
]
178185
},

‎docs/esa-deploy.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# 使用阿里云 ESA Pages 和边缘函数部署文档
2+
3+
本文档介绍如何使用阿里云边缘安全加速（ESA）的 Pages 服务和边缘函数（Edge Function）来构建和部署 DDNS 文档站点。
4+
5+
> 关于如何让ESA支持动态地址解析(DDNS) 请参考 [DDNS 阿里云边缘安全加速 (ESA) 配置指南](./providers/aliesa.md)
6+
7+
## 总结
8+
9+
通过阿里云 ESA Pages 和边缘函数，加速国内用户：
10+
11+
1. ✅ **静态生成 [Pages]**：根据 Markdown 自动构建和部署 VitePress 文档
12+
2. ✅ **混合加载**：支持客户端切换页面无刷新加载
13+
3. ✅ **边缘计算 [Function]**：使用边缘函数实现高级功能
14+
- **下载加速**：对 GitHub Releases 发布的文件进行加速
15+
- **动态版本**：支持 beta 等动态版本解析
16+
- **旧链重定向**：将旧版链接自动重定向到新页面
17+
4. ✅ **全球加速**：享受全球边缘节点加速和免费 HTTPS
18+
19+
## 概述
20+
21+
- **静态网站生成**：自动构建和部署 VitePress 文档
22+
- **边缘函数**：在边缘节点运行 JavaScript 代码，处理动态请求
23+
- **全球加速**：通过全球边缘节点加速内容分发
24+
- **自动 HTTPS**：免费 SSL/TLS 证书
25+
- **自定义域名**：支持绑定自定义域名
26+
27+
### 流程
28+
29+
```text
30+
+-----------+
31+
| 客户端请求 |
32+
+-----+-----+
33+
|
34+
v
35+
+-----+------+
36+
| ESA 边缘节点|
37+
+-----+------+
38+
|
39+
+-----+------+
40+
| 请求内容判断|
41+
+-----+------+
42+
|
43+
+-------------+-----------+
44+
| |
45+
动态内容请求 静态页面请求
46+
| |
47+
v v
48+
+-----+-----+ +------+----+
49+
(GithubAPI)-->| 函数模块 |<--(缓存)-->| 缓存模块 |<--(静态资源)
50+
+-----+-----+ +------+----+
51+
| |
52+
+------------+------------+
53+
|
54+
v
55+
+------+------+
56+
| 返回响应内容 |
57+
+-------------+
58+
```
59+
60+
61+
## 部署步骤
62+
63+
### 第一步：创建 ESA Pages 项目
64+
65+
1. 登录 [阿里云 ESA 控制台](https://esa.console.aliyun.com/)
66+
67+
2. 在左侧导航栏选择 **"Pages"**
68+
69+
3. 点击 **"创建项目"** 按钮
70+
71+
4. 配置项目基本信息：
72+
- **项目名称**：`ddns-docs`（可自定义）
73+
- **连接 GitHub**：授权 ESA 访问您的 GitHub 账号
74+
- **选择仓库**：`NewFuture/DDNS`
75+
- **选择分支**：`master`
76+
77+
### 第二步：配置构建设置
78+
79+
在项目构建配置中，ESA Pages 会自动检测并读取 `docs/esa.jsonc` 文件中的配置。
80+
81+
项目中已包含 `docs/esa.jsonc` 配置文件：
82+
83+
```jsonc
84+
{
85+
"name": "ddns",
86+
"entry": "esa.js", // 边缘函数入口文件
87+
"installCommand": "npm install", // 安装依赖命令
88+
"buildCommand": "npm run build", // 构建命令
89+
"assets": {
90+
"directory": ".vitepress/dist", // 静态资源目录
91+
"notFoundStrategy": "404Page" // 404 页面策略
92+
}
93+
}
94+
```
95+
96+
**配置说明**：
97+
98+
| 配置项 | 说明 | 值 |
99+
|--------|------|-----|
100+
| `name` | 项目名称 | `ddns` |
101+
| `entry` | 边缘函数入口文件 | `esa.js`（可选，用于高级功能） |
102+
| `installCommand` | 安装依赖命令 | `npm install` |
103+
| `buildCommand` | 构建命令 | `npm run build` |
104+
| `assets.directory` | 构建输出目录 | `.vitepress/dist` |
105+
| `assets.notFoundStrategy` | 404 处理策略 | `404Page` |
106+
107+
::: tip
108+
ESA Pages 会自动检测并应用 `esa.jsonc` 配置，无需手动配置构建参数。
109+
:::
110+
111+
### 第三步：部署边缘函数（可选）
112+
113+
DDNS 项目包含一个边缘函数 `docs/esa.js`，用于实现以下功能：
114+
115+
1. **Release 代理**：统一格式代理 GitHub Releases 文件
116+
- 支持 `/releases/latest/`、`/releases/beta/`、`/releases/v4.1.3/` 等路径
117+
- 自动缓存和流式传输
118+
119+
2. **URL 重定向**：处理旧版文档 URL 的重定向
120+
- `/doc/*` → `/` （301 重定向）
121+
- `/index.en.html` → `/en/` （301 重定向）
122+
- `/doc/*.en.html` → `/en/*.html` （301 重定向）
123+
124+
#### 边缘函数部署
125+
126+
边缘函数会随 Pages 项目自动部署，但需要进行以下配置：
127+
128+
1. **创建 EdgeKV 命名空间**（用于缓存 beta 版本信息）：
129+
- 在 ESA 控制台选择 **"EdgeKV"**
130+
- 点击 **"创建命名空间"**
131+
- 命名空间名称：`ddns-releases`
132+
133+
2. **配置路由规则**：
134+
- 在 Pages 项目设置中，边缘函数会自动绑定
135+
- 确认路由规则包含 `/releases/*` 和其他需要处理的路径
136+
137+
3. **验证功能**：
138+
```bash
139+
# 测试 release 代理
140+
curl -I https://your-domain.com/releases/latest/ddns-windows-x64.exe
141+
142+
# 测试重定向
143+
curl -I https://your-domain.com/doc/install.html
144+
```
145+
146+
::: warning
147+
边缘函数使用了 EdgeKV 存储 beta 版本映射，需要确保 EdgeKV 命名空间 `ddns-releases` 已创建并且项目有访问权限。
148+
:::
149+
150+
151+
## 构建和部署流程
152+
153+
### 构建流程
154+
155+
当代码推送到 GitHub 后，ESA Pages 会自动执行以下步骤：
156+
157+
```bash
158+
# 1. 切换到文档目录
159+
cd docs
160+
161+
# 2. 安装依赖（由 esa.jsonc 的 installCommand 配置）
162+
npm install
163+
164+
# 3. 构建文档（由 esa.jsonc 的 buildCommand 配置）
165+
npm run build
166+
# 实际执行: vitepress build .
167+
168+
# 4. 部署静态文件（从 .vitepress/dist 目录）
169+
```
170+
171+
### VitePress 构建说明
172+
173+
DDNS 文档使用 VitePress 2.0 构建，构建过程包括：
174+
175+
1. **预处理**：
176+
- 复制 `README.md` → `docs/index.md`
177+
- 复制 `README.en.md` → `docs/en/index.md`
178+
- 通过符号链接访问 `schema/` 目录
179+
180+
2. **构建静态站点**：
181+
- 编译 Markdown 为 HTML
182+
- 生成 sitemap.xml
183+
- 生成 llms.txt（AI 上下文文件）
184+
- 优化资源文件
185+
186+
3. **输出**：
187+
- 输出到 `docs/.vitepress/dist/` 目录
188+
- 包含所有静态资源（HTML、CSS、JS、图片等）
189+
190+
## 高级配置
191+
192+
### 环境变量
193+
194+
如果需要在构建过程中使用环境变量，可以在 Pages 项目设置中添加： `TZ`: `Asia/Shanghai`.
195+
196+
## 边缘函数详解
197+
198+
### Release 代理功能
199+
200+
边缘函数 `esa.js` 实现了统一的 Release 文件访问格式：
201+
202+
```
203+
/releases/{version}/{binary_file}
204+
```
205+
206+
**支持的版本标识**：
207+
208+
- `latest`：最新稳定版
209+
- 示例：`/releases/latest/ddns-windows-x64.exe`
210+
- 缓存策略：12 小时缓存
211+
- 实际指向 GitHub 的 latest release
212+
213+
- `beta`：最新测试版
214+
- 示例：`/releases/beta/ddns-glibc-linux_amd64`
215+
- 缓存策略：转换为具体版本后无限缓存
216+
- 通过 GitHub API 动态查询最新 prerelease
217+
218+
- 具体版本号：
219+
- 示例：`/releases/v4.1.3-beta1/ddns-mac-arm64`
220+
- 缓存策略：无限缓存（immutable）
221+
- 直接指向 GitHub 对应版本
222+
223+
**工作原理**：
224+
225+
```javascript
226+
// 1. 解析请求路径
227+
/releases/{version}/{binary_file}
228+
229+
// 2. 根据版本类型构建 GitHub URL
230+
// latest: https://github.com/NewFuture/DDNS/releases/latest/download/{binary_file}
231+
// beta: 查询 GitHub API 获取最新 prerelease 版本号，转换为具体版本
232+
// v4.1.3: https://github.com/NewFuture/DDNS/releases/download/v4.1.3/{binary_file}
233+
234+
// 3. 从 GitHub 获取文件，设置缓存策略
235+
// 4. 流式传输给客户端
236+
```
237+
238+
### URL 重定向功能
239+
240+
边缘函数处理旧版文档 URL 的 301 重定向：
241+
242+
| 旧 URL | 新 URL | 说明 |
243+
|--------|--------|------|
244+
| `/index.en.html` | `/en/` | 英文主页重定向 |
245+
| `/doc/install.en.html` | `/en/install.html` | 英文文档重定向 |
246+
| `/doc/install.html` | `/install.html` | 中文文档重定向 |
247+
| `/doc/providers/dnspod.html` | `/providers/dnspod.html` | 所有文档路径去除 `/doc/` 前缀 |
248+
249+
### EdgeKV 使用
250+
251+
边缘函数使用 EdgeKV 存储 beta 版本映射，避免频繁调用 GitHub API：
252+
253+
```javascript
254+
// 存储结构
255+
{
256+
"ddns-beta-version": "v4.1.3-beta1" // 缓存 6 小时
257+
}
258+
```
259+
260+
- 减少 GitHub API 调用次数
261+
- 降低 API 速率限制风险
262+
- 提高响应速度
263+
264+
## 监控和日志
265+
266+
### 构建日志
267+
268+
1. 在 Pages 项目页面查看 **"部署历史"**
269+
2. 点击任意部署记录查看详细构建日志
270+
3. 日志包含：
271+
- 依赖安装输出
272+
- VitePress 构建输出
273+
- 死链检查结果
274+
- 部署状态
275+
276+
### 边缘函数日志
277+
278+
1. 在 ESA 控制台选择 **"边缘函数"**
279+
2. 选择对应的函数
280+
3. 查看 **"实时日志"** 或 **"历史日志"**
281+
282+
## 成本和限额
283+
284+
### ESA Pages 配额
285+
286+
根据阿里云 ESA 的定价策略：
287+
288+
- **免费额度**（新用户试用）：
289+
- 每月 100GB 流量
290+
- 1000 万次请求
291+
- 10 万次边缘函数调用
292+
293+
### EdgeKV 配额
294+
295+
- **命名空间**：每个账号最多 10 个
296+
- **存储空间**：每个命名空间最大 1GB
297+
- **操作次数**：每月 1000 万次读写操作（免费额度）
298+
299+
300+
## 参考资源
301+
302+
- [阿里云 ESA 产品文档](https://help.aliyun.com/product/122312.html)
303+
- [阿里云 ESA Pages 文档](https://help.aliyun.com/zh/edge-security-acceleration/esa/user-guide/pages-service-overview)
304+
- [阿里云 ESA 边缘函数文档](https://help.aliyun.com/zh/edge-security-acceleration/esa/user-guide/edge-functions-overview)
305+
- [VitePress 官方文档](https://vitepress.dev/)
306+
- [DDNS GitHub 仓库](https://github.com/NewFuture/DDNS)
307+
308+
Tags: #阿里云ESA Pages #阿里云云工开物

0 commit comments

Comments
 (0)