EdgeOne CDN Deployment — Verified Setup Guide¶
Site: docs.omnivoltaic.cn | Origin: COS oves-cos-bucket-1437812500 (ap-singapore)
Plan: Personal ¥9.9/mo | Verified: 2026-08-10 | Status: ✅ Live
Critical Configuration (exactly as verified)¶
| Component | Setting | Notes |
|---|---|---|
| EdgeOne site | omnivoltaic.cn, CNAME mode, Global region |
NOT EdgeOne Pages |
| Acceleration domain | docs (host record only) |
Full domain: docs.omnivoltaic.cn |
| Origin type | 对象存储源站 → 腾讯云COS | NOT IP/域名, NOT static website |
| Origin domain | Default COS domain (auto) | e.g. bucket.cos.ap-singapore.myqcloud.com |
| Private access auth | ON (required) | Auto-grants EdgeOne read access to private COS bucket |
| Origin protocol | 协议跟随 (Follow) | Default |
| File format (crucial) | use_directory_urls: false in mkdocs |
Pages are /page.html, not /page/ |
| Path rewrite rule | 规则引擎 → 回源URL重写 → 增加前缀 /docs/ |
Without this, docs.omnivoltaic.cn/tencent-cloud/ fetches COS /tencent-cloud/ |
| DNS CNAME | docs → docs.omnivoltaic.cn.eo.dnse1.com |
Value changes per domain — copy from EdgeOne |
Build Settings (mkdocs)¶
site_url: "https://docs.omnivoltaic.cn/tencent-cloud/"
use_directory_urls: false # CRITICAL — flat .html files avoid COS directory index issue
Build command:
cd <repo>
python -m mkdocs build -d ./site
Upload to COS¶
unset HTTPS_PROXY HTTP_PROXY ALL_PROXY # CRITICAL — avoid proxy blocking SDK
node cos_node.mjs upload --file site/index.html --key docs/tencent-cloud/index.html --bucket oves-cos-bucket-1437812500 --region ap-singapore
Unset HTTPS_PROXY is essential — the COS SDK inherits environment proxy settings which may be dead.
CONSOLE STEPS — 1-2-3¶
1. Create Site (one-time)¶
https://console.cloud.tencent.com/edgeone → 网站安全加速 tab → 添加站点
- 站点名称: omnivoltaic.cn
- 套餐: 个人版 ¥9.9/mo
- 加速区域: 全球可用区
- 接入模式: CNAME 接入
- 验证: DNS 验证 (add TXT record at apex)
2. Add Domain (once per subdomain)¶
Site → 域名服务 → 域名管理 → 添加域名
- 加速域名: docs (host only, not docs.omnivoltaic.cn)
- 源站配置: 对象存储源站 → 腾讯云COS → select bucket
- 私有访问授权: ON
- 保存
3. Add Path Rewrite Rule (once per subdomain)¶
Site → 规则引擎 → 新建规则 → 新建空规则
- 匹配类型: 全部请求 (or host header match)
- 操作: 回源 URL 重写 → 增加前缀 → /docs/
- 保存并发布
4. DNS CNAME¶
Tencent DNS → add docs CNAME → EdgeOne-assigned value
5. HTTPS (after DNS resolves)¶
Domain → HTTPS配置 → 申请免费证书
Adding More Subdomains¶
Copy steps 2-5 for each new subdomain:
| Subdomain | Path Prefix | Example URL |
|---|---|---|
docs.omnivoltaic.cn |
/docs/ |
docs.omnivoltaic.cn/tencent-cloud/ |
decks.omnivoltaic.cn |
/decks/ |
decks.omnivoltaic.cn/pitch/ |
memo.omnivoltaic.cn |
/memo/ |
memo.omnivoltaic.cn/2026-08-10/ |
training.omnivoltaic.cn |
/training/ |
training.omnivoltaic.cn/module-1/ |
media.omnivoltaic.cn |
/media/ |
media.omnivoltaic.cn/product-photos/ |
What NOT to Try¶
| ❌ Dead End | Why | ✅ Correct |
|---|---|---|
| EdgeOne Pages | One project per domain, no shared edge functions | Web 安全加速 (CDN) |
| COS 静态网站 origin | Grayed out or breaks private access | Default COS domain + use_directory_urls: false |
use_directory_urls: true |
COS doesn't serve index.html from directory paths | false — explicit .html extensions |
| Switching to IP/域名 origin | Loses private access, requires manual COS website URL | Stay on 对象存储源站 |
| Uploading with proxy on | ECONNRESET — dead proxy blocks SDK |
unset HTTPS_PROXY HTTP_PROXY |
Troubleshooting¶
| Symptom | Check |
|---|---|
| 403 AccessDenied | Private access authorization off — toggle ON in origin settings |
| 404 NoSuchKey | File not uploaded OR path rewrite rule missing OR wrong file URL |
| CNAME not resolving | DNS propagation — wait 5-30 min |
| No HTTPS | Apply free certificate in domain HTTPS settings |
docs.omnivoltaic.cn resolves to Pages |
Old CNAME from Pages project still in DNS — delete it |