0更新日志
2026-08-18 22:20:25
# 星辉云端 · 博客系统 开发总结
> 跨越多天的长期项目总结：控制台（星辉云端）+ 博客（XHBlogs）双端维护
---
## ⏱ 总时长
- 跨越多天、多次会话的持续开发项目
- 涉及：内容管理、性能优化、部署迁移、评论系统、音乐系统、域名绑定
## 💰 总花费
- **域名 fall07.top**：腾讯云首年（十几元内）
- 其余**全部免费**：Cloudflare、Netlify、MongoDB Atlas、GitHub、腾讯云（未购买任何捆绑服务）
---
## ⚙️ 一、控制台（星辉云端 my-blog-manager）——核心管理后台
### 架构与稳定化
1. **端口固定**：前端 `5155`、API `5156`（不再随机，浏览器收藏永远有效）
2. **API 子进程隔离**：uvicorn 从线程改 `subprocess.Popen`，解决 pywebview 线程冲突导致 API 无限超时（实测 51ms）
3. **构建自愈**：run_me.py 自动检测 standalone 构建产物，缺失自动重建
4. **桌面一键启动**：`星辉云端-一键启动.bat` → `console_launcher.ps1`（已运行则激活窗口，未运行则清理重启）
### 内容 / 发布链路
5. **一键上线**：`publishNow.ts`（sync/execute → deploy/source），编辑器/说说/导航栏都可直接发布
6. **Standalone 内容同步**：发布/删除后自动镜像内容到 `.next/standalone`，首页即时刷新
7. **动态渲染**：首页/灵境页 `force-dynamic`，发布即见
8. **sync.py 升级**：`SYNC_COMPONENTS` 组件同步（控制台为源 → 博客）
### UI / 体验
9. **Navbar 刷新按钮** + F5 快捷键
10. **移除弹幕视觉**（功能保留）
11. **性能优化**：删 WindyGrass、去全屏 backdrop-blur、减少粒子数量、静态背景
---
## ⚙️ 二、博客（XHBlogs → GitHub → 部署平台）
### 性能优化
12. 与控制台同步的性能优化（背景、粒子、动画）
### 评论区（Twikoo）——最大工程
13. Twikoo 动态 import 修复（兼容打包导出结构）
14. **twikoo 服务迁移**：腾讯云（免费套餐跑不了 `FreePackageDenied`）→ **Netlify + MongoDB Atlas**（免费）
15. **CORS 修复**：关掉 Netlify 认证保护（Private → Public），评论区恢复
### 部署 / 访问加速
16. **从 Vercel 迁到 Cloudflare Pages**：纯静态导出，国内访问加速
17. **自定义域名 fall07.top**：绑定成功，替代 pages.dev
18. **微信打不开**：加验证文件申诉（`6a6d9417...txt`）
### 音乐系统
19. **音乐卡死根治**：mp3 从 vercel.app（国内超时）→ 本地 `/music/` 路径
20. **防卡死保护**：onError 自动跳、超时自动跳过、preload 优化
### 其他
21. **字体本地化**：Geist + Noto Serif SC 下载到本地，摆脱 Google Fonts 依赖，视觉保留
22. **app/api 移 `_legacy_api`**：保留代码，未来可恢复动态功能
---
## 🐛 主要 Bug 修复汇总
1. 音乐播放卡死（源文件超时）
2. 评论区空白（腾讯云免费套餐限制）
3. CORS 跨域拦截
4. 微信域名拦截
5. DNS 绑定各种问题（CNAME 填错、Workers 占用、522）
6. API 无限超时（uvicorn 线程冲突）
7. twikoo 打包导出结构不兼容
8. 构建时 Google Fonts 下载失败
---
## 🚀 核心优化汇总
1. 国内访问加速（Cloudflare + 静态导出 + 本地资源）
2. 字体构建不依赖 Google
3. 音乐本地化 + 防卡死
4. 评论系统免费稳定（Netlify）
5. 控制台稳定化（固定端口、子进程隔离、自愈）
6. 一键发布 / 部署链路