OneBlog部署

OneBlog 部署文档

文档版本：2026-07-06
仓库：https://cnb.cool/onedayxyy/hugo-teek-private
博客站点：https://onedayxyy.cn
管理后台：https://oneblogadmin.onedayxyy.cn

目录

1. 项目简介
2. 技术架构
3. 特色优势
4. 部署文档
   • 4.1 整体部署拓扑
   • 4.2 前置准备与密钥清单
   • 4.3 博客前台部署（Hugo → COS → EdgeOne CDN）
   • 4.4 博客后台部署到 EdgeOne Pages（重点）
   • 4.5 CNB CI 流水线说明
   • 4.6 Gitee 备份同步
   • 4.7 本地开发联调
   • 4.8 验证与排错
5. 待优化项
6. 附录

版权

次项目是在上游 余温大佬开发的 Hugo Teek / RouxZhee 主题能力之上 二开的，增加了可视化运维后台（基于 PrimeEdge Admin 适配），使用户可以在浏览器中编辑 Markdown、调整站点配置、上传媒体，而无需在本机安装 Hugo 或手工改 Git。

感谢余温大佬开发的优秀项目❤️❤️❤️（也感谢KOK大佬贡献的基于EO的博客后台）

仓库地址

待更新。

1. 项目简介

OneBlog 是一套「静态博客 + Web 管理后台」一体的个人站全栈方案，以 monorepo 形态托管于腾讯云开发者平台 CNB（Cloud Native Build）。

它在上游 Hugo Teek / RouxZhee 主题能力之上，增加了可视化运维后台（基于 PrimeEdge Admin 适配），使作者可以在浏览器中编辑 Markdown、调整站点配置、上传媒体，而无需在本机安装 Hugo 或手工改 Git。

核心产品定位：

• 面向技术博客 / 文档库 / 个人知识站
• 「Git 即数据库」：文章、文档、TOML/JSON 配置全部落盘在 Git，可版本回滚
• 「无传统服务端数据库」：后台态用 EdgeOne KV，内容态用 Git
• 「保存即可发布」：Admin 写入 → commit/push → CNB CI 构建 → COS + CDN 刷新

1.1 仓库目录一览

 1hugo-teek-private/
 2├── hugo-teek-site/           # Hugo 站点（内容、主题、静态资源）
 3│   ├── content/              # posts / docs 等 Markdown
 4│   ├── data/                 # 侧边栏、分析、图库等数据
 5│   ├── themes/hugo-teek/     # Teek 移植主题
 6│   └── static/               # 静态资源
 7├── user-configuration/       # 用户层配置（覆盖主题默认）
 8│   ├── hugo.toml
 9│   ├── themes/hugo-teek/*.toml
10│   └── teek-plugins/*.toml
11├── oneblog-admin/            # EdgeOne Pages：Functions + public 输出
12│   ├── functions/            # Edge Functions（API / SPA / 静态透传）
13│   ├── public/               # EO 静态输出目录
14│   └── edgeone.json
15├── admin-frontend/           # Vue3 + Element Plus 管理前端（build 产物写入 oneblog-admin/public）
16├── bin/                      # Windows/Linux 构建工具与 Hugo 二进制
17├── .cnb.yml                  # CNB CI：构建、COS、EO Admin、Gitee 备份
18├── Makefile                  # 本地 / Docker 构建入口
19└── LOCAL_DEV.md              # 本地开发快速指南

2. 技术架构

2.1 架构总览

截图：

2.2 分层说明

2.3 数据流：保存一篇文章发生了什么

1. 作者在 oneblogadmin.onedayxyy.cn 登录（JWT + HttpOnly Cookie）。
2. 编辑 Markdown，点保存。
3. Edge Function 将内容 Base64（大文件可 gzip） 提交给 CNB 流水线 api_trigger_admin_write。
4. CI Runner 落盘到目标路径 → git commit → git push origin master。
5. master.push 流水线启动：
   • 同步到 Gitee 备份仓
   • make build-docker 构建 Hugo
   • coscli sync 推送到 COS -（若改动了后台代码）edgeone makers deploy 更新 Admin
   • EdgeOne CDN 路径刷新 + 钉钉通知
6. 读者访问 https://onedayxyy.cn 获取最新静态页。

2.4 配置合并模型

线上与本地一致，采用「用户配置覆盖默认主题配置」：

1. user-configuration/：你在后台或手工维护的配置真相源
2. hugo-teek-tools config merge：合并进 hugo-teek-site/config/_default/
3. Hugo 构建读取合并结果

因此：改配置只改 user-configuration/，不要直接改构建产物目录。

3. 特色优势

3.1 GitOps 式内容管理

• 每篇文档都是可跟踪、可回滚、可协作的 Git 对象
• 无独立 CMS 数据库，避免数据割裂与厂商锁定
• 后台写入与手工 git push 走同一条 CI，行为一致

3.2 前后台分离但同仓协作

• 博客站点与 Admin 同 monorepo，发版、备份、权限一套即可
• Admin 仅在 oneblog-admin/** 或 admin-frontend/** 变更时重新部署，避免每次改文都重部署后台

3.3 Edge 原生后台，成本低、运维轻

• EdgeOne Pages Functions + KV，无需自建 Node/PHP 宿主机
• 登录限流、密钥注入均在边缘侧完成
• 静态 SPA + catch-all Function 分路由处理 API / 页面 / 静态资源透传

3.4 Hugo 极速构建 + Teek 级阅读体验

• VitePress Teek 风格 UI、暗色模式、三栏文档布局
• FlexSearch 离线全文搜索
• Twikoo 评论、多种统计、VitePress 容器语法自动转换
• 响应式首页卡片、波浪封面、侧栏组件等定制能力

3.5 可本地、可云端双模式

本地改完 → git push origin master 即可上线。

3.6 备份与可观测性

• Gitee 只读镜像式备份（git-sync，含 tags）
• 构建耗时统计 + 钉钉完成通知
• Admin /api/setup/status 诊断密钥是否就绪

3.7 媒体与配置备份能力

七牛侧约定布局：

4. 部署文档

4.1 整体部署拓扑

生产环境由三条主链路组成：

不要把整个博客静态站部署到 EdgeOne Pages 作为主发布路径。 当前博客体量大，Hugo 构建在 CNB Docker 中完成，再 coscli sync 到 COS，由 EdgeOne CDN 源站 加速；Pages 只承载 管理后台。

4.2 前置准备与密钥清单

账号与产品

• 腾讯云账号，开通：CNB、COS、EdgeOne（CDN + Pages）
• （可选）七牛云 Kodo
• （可选）钉钉群机器人
• （可选）Gitee 私人仓库作备份

CNB Secret（https://cnb.cool/onedayxyy/secret → envs.yml）

建议至少包含：

CNB Runner 通过 .cnb.yml 的 imports 注入上述密钥，不要把真实密钥写进仓库。

EdgeOne Pages 环境变量（Admin 项目）

见 4.4.3。

CNB Token（供 Admin 写入）

在 CNB 个人设置中创建访问令牌，权限建议：

4.3 博客前台部署（Hugo → COS → EdgeOne CDN）

4.3.1 COS 桶准备

1. 创建私有或公有读 Bucket（与 COS_BUCKET 一致）。
2. 该桶作为 EdgeOne CDN 源站。
3. 确认 coscli 使用的密钥具备列表与写入权限。

4.3.2 EdgeOne CDN（博客域名）

1. EdgeOne 控制台添加站点 onedayxyy.cn。
2. 源站指向上述 COS 桶（或加速域名）。
3. HTTPS 证书自动签发或上传自有证书。
4. 首页路由与静态资源按默认对象存储源即可；Hugo 已输出完整 HTML。

4.3.3 CNB 仓库与流水线

1. 将本仓库推送到 cnb.cool/onedayxyy/hugo-teek-private。
2. .cnb.yml 已包含：
   • master.push：备份 → 构建 → COS →（条件）Admin → CDN → 钉钉
   • web_trigger：控制台手动「构建＆部署」
   • api_trigger_admin_write：后台写文件
   • api_trigger_rebuild：后台手动重建
3. Secret 库 envs.yml 已在 imports 中引用。
4. Docker 镜像：docker.cnb.cool/yuwen-gueen/docker-images-chrom/hugo-teek-blog:latest（内置 Hugo、hugo-teek-tools）。

4.3.4 手动触发一次发布（验证）

1# 在本机推送到 CNB master
2git push origin master

或在 CNB 页面使用 构建＆部署（web_trigger）。

成功标志：

• Runner 阶段 build 与「部署到 cos」为绿色
• 访问 https://onedayxyy.cn/ 内容已更新（注意 CDN 刷新后可能仍有极短缓存）

4.3.5 核心构建命令（理解即可）

CI 中实际执行：

1make build-docker
2# 合并配置 → frontmatter → permalink → index → sidebar → VitePress 转换
3# → doc analysis → search index → hugo --minify
4# 输出：hugo-teek-site/public

随后：

1coscli sync ./hugo-teek-site/public cos://$COS_BUCKET/ -r \
2  --delete --force --routines=1000 --thread-num=1000

CDN 刷新（首页路径示例）：

1kind: tencenteo
2rtype: path
3domain: onedayxyy.cn
4urls: https://onedayxyy.cn/

如需全站更强一致，可在流水线中扩展刷新 URL 列表（注意接口配额）。

4.4 博客后台部署到 EdgeOne Pages（重点）

生产后台项目名：oneblog-admin，域名：oneblogadmin.onedayxyy.cn。

后台由两部分组成，部署前需理解：

edgeone.json 关键内容：

1{
2  "name": "oneblog-admin",
3  "version": "1.0.0-mvp",
4  "outputDirectory": "public",
5  "bindings": [
6    { "type": "kv", "name": "ADMIN_KV" }
7  ]
8}

4.4.1 方式一：CNB 自动部署（推荐生产流程）

仓库已内置：当 oneblog-admin/** 或 admin-frontend/** 变更并 push 到 master 时：

1- name: deploy to edgeone makers
2  ifModify:
3    - "oneblog-admin/**"
4    - "admin-frontend/**"
5  image: node:20
6  script: |
7    cd admin-frontend && npm ci && npm run build && cd ..
8    test -f oneblog-admin/public/admin/index.html
9    npx edgeone makers deploy ./oneblog-admin -n oneblog-admin -t $EDGEONE_API_TOKEN

前置条件：

1. Secret 中已配置 EDGEONE_API_TOKEN（EdgeOne API 令牌，具备 Pages / Makers 部署权限）。
2. EdgeOne Pages 上已存在项目名 oneblog-admin（首次需手工创建一次，见 4.4.2）。
3. Pages 项目侧环境变量、KV、自定义域名已配好（CLI 不会自动同步 QINIU_*、ADMIN_PASSWORD 等密钥，必须在控制台维护）。

日常更新后台：

1# 修改 admin-frontend 或 oneblog-admin 后
2git add admin-frontend oneblog-admin
3git commit -m "feat(admin): ..."
4git push origin master

等 CI 中 deploy to edgeone makers 成功后，访问 https://oneblogadmin.onedayxyy.cn 验证。

仅改博客正文（hugo-teek-site/content）时，Admin 不会 重新部署，仅重建前台。这是预期行为。

4.4.2 方式二：控制台首次创建 Pages 项目

适用于第一次把后台放到 EO，或 CI Token 不可用时的手工部署。

步骤：

1. 打开 EdgeOne Pages 控制台。
2. 新建项目 → 关联 Git 仓库 hugo-teek-private（若平台支持 CNB/导入压缩包，则导入 oneblog-admin 目录内容）。
3. 构建配置（强烈建议）：

若希望控制台构建也最新 SPA，可将构建命令设为（需把根目录设为仓库根，并调整输出路径，复杂度更高——更推荐用 CNB 构建 + makers deploy）：

1cd admin-frontend && npm ci && npm run build

输出仍为 oneblog-admin/public。

4. 添加 KV 命名空间绑定：

• 绑定名称必须为：ADMIN_KV
• 类型：KV
• 与 edgeone.json → bindings[].name 一致

5. 保存并首次部署。部署完成后会得到形如 *.edgeone.cool 的默认域名。

4.4.3 配置环境变量与 KV

混清点先讲清：

推荐：方式 A — Pages 环境变量（更清晰、更安心）

项目设置 → 环境变量：

* 未配置七牛时，云存储相关能力回退 Git 图床。

修改环境变量后需要 重新部署 Pages 才生效。

方式 B — 在 ADMIN_KV 中写数据键

适用于不想把密码放在环境变量列表、或希望改密钥后无需重新部署的场景：

KV 变更通常 无需重新部署。

健康检查：

1GET https://oneblogadmin.onedayxyy.cn/api/setup/status

期望：ready: true，且 sources 标明 kv 或 env（表示已读到密钥）。

示例（结构示意）：

1{
2  "ready": true,
3  "sources": {
4    "ADMIN_PASSWORD": "env",
5    "JWT_SECRET": "env",
6    "GIT_TOKEN": "env"
7  }
8}

4.4.4 绑定自定义域名

1. Pages 项目 → 域名管理 → 添加 oneblogadmin.onedayxyy.cn。
2. 在域名 DNS（如已由 EdgeOne 托管 onedayxyy.cn，在站点 DNS 下）添加控制台提示的 CNAME。
3. 等待 SSL 证书签发。
4. 访问 https://oneblogadmin.onedayxyy.cn/，应出现登录页。

4.4.5 本机 CLI 手工部署（应急）

需本机安装 Node.js 20+，并有 EDGEONE_API_TOKEN：

 1# 在仓库根目录
 2cd admin-frontend
 3npm ci
 4npm run build
 5cd ..
 6
 7# 确认 SPA 产物存在
 8test -f oneblog-admin/public/admin/index.html   # Linux/macOS
 9# Windows PowerShell:
10# Test-Path oneblog-admin/public/admin/index.html
11
12npx edgeone makers deploy ./oneblog-admin -n oneblog-admin -t $EDGEONE_API_TOKEN

Windows PowerShell：

1$env:EDGEONE_API_TOKEN = "你的Token"
2cd admin-frontend
3npm ci
4npm run build
5cd ..
6npx edgeone makers deploy ./oneblog-admin -n oneblog-admin -t $env:EDGEONE_API_TOKEN

注意： CLI 不会改写控制台里的环境变量；QINIU_* / ADMIN_PASSWORD 等仍需在 EO 控制台维护。

4.4.6 首次登录与系统设置

1. 打开 https://oneblogadmin.onedayxyy.cn/。
2. 使用 ADMIN_PASSWORD 登录。
3. 进入 系统设置 → Git 仓库：
   • 平台：CNB
   • Owner：onedayxyy
   • Repo：hugo-teek-private
   • Branch：master
   • Token：已由环境变量注入时可为空；未注入则在此填写并保存到 KV
4. 点击 测试连接。
5. 使用 文档管理 / 文章管理 / 站点配置 试保存一篇内容。
6. 到 CNB 流水线确认 api_trigger_admin_write → master.push 成功。
7. 打开 https://onedayxyy.cn 验证前台。

4.4.7 Admin 路由与静态资源机制（理解排错）

关键文件：

1oneblog-admin/functions/
2├── [[default]].js     # API + /admin SPA 回退
3├── js/[[path]].js     # /js/* 透传（优先于 catch-all）
4├── css/[[path]].js    # /css/* 透传
5├── version.json.js
6└── index.js           # 登录页 /

常见故障：登录后侧栏在、主区空白。

Workaround / 根因：

• functions/[[default]].js 会拦截未匹配路由；若 /js/app.js、/css/style.css 未从正确 public/ 发布，或被 catch-all 先吞，前端脚本 404，主区空白。
• 本仓库已通过 outputDirectory: public + 专属 js/[[path]].js、css/[[path]].js 透传修复。

排查步骤：

1. DevTools → Network：确认 /js/app.js、/css/style.css、/admin/、/admin/assets/* 为 200。
2. 确认 Pages 根目录为 oneblog-admin，输出目录为 public。
3. 确认 public/admin/index.html 在部署包内存在（CI 已有 test -f 守护）。
4. 修改后必须重新 edgeone makers deploy 或等待 CI。

4.5 CNB CI 流水线说明

大文件写入：Admin 侧 prepareCnbWritePayload() 对超限内容启用 ADMIN_WRITE_ENCODING=gzip，Runner 用 gunzip 解压后写入，避免「文件过大无法经后台写入」类错误。当前写接口字节上限接近约 96KB（Base64 后），gzip 后通常远低于此。

4.6 Gitee 备份同步

master.push 阶段使用 tencentcom/git-sync：

1target_url: https://gitee.com/onlyonexl/ongblog-gitee-backup.git
2branch: master
3force: true
4push_tags: true

Secret 需提供：

• GIT_USERNAME：Gitee 用户名
• GIT_ACCESS_TOKEN：具备 projects 写权限的私人令牌

Gitee 不是 CI 构建源，仅作备份。请勿把 Admin 默认远程改到仅有 Gitee 而无 CNB CI 的仓。

4.7 本地开发联调

详见根目录 LOCAL_DEV.md。摘要：

依赖：Hugo Extended、Node.js 18+、pnpm（脚本可协助安装）。仓库已附带 bin/windows 工具链。

本地保存后需自行：

1git add user-configuration hugo-teek-site
2git commit -m "更新站点配置"
3git push origin master

线上 Admin 保存则自动 commit/push，无需本机介入。

4.8 验证与排错

5. 待优化项

结合当前仓库实现与运维现状，建议按优先级推进如下优化。

5.1 高优先级（稳定性 / 成本 / 体验）

5.2 中优先级（后台功能完善）

5.3 工程与质量

5.4 前台体验

5.5 安全相关建议

6. 附录

6.1 相关文件索引

6.2 生产 URL 速查

6.3 一键「内容保存 → 上线」心智模型

 1Admin 保存
 2  → Edge Function
 3  → CNB api_trigger_admin_write（落盘 + commit + push）
 4  → master.push
 5      → Gitee backup
 6      → Hugo build (Docker)
 7      → COS sync
 8      → CDN refresh
 9      → 钉钉通知
10  → 读者看到更新

后台代码变更额外多一步：

1admin-frontend / oneblog-admin 变更进 master
2  → npm run build
3  → edgeone makers deploy ./oneblog-admin

文档维护： 部署架构变更（域名、存储、CI 阶段）时，请同步更新本文档日期与对应章节。

oneblog / hugo-teek-private · 2026-07-06