脚本概览
PowerShell · Python · CGI · 自动化
|
脚本——构建用 PowerShell，服务端用 Python
CGI，加起来二十多个文件。这里统一介绍一下它们做什么、支持哪些参数，方便以后回来查。
|
构建系统（PowerShell）
构建系统是网站的骨架。五个脚本按固定顺序运行：先扫描文章元数据生成归档和索引，再逐页拼接
HTML 组件，最后输出 RSS 和 sitemap。全部放在
scripts/ 下。
build.ps1 —— 单页面构建
读取一个内容文件和所有 HTML
组件（header、banner、footer、侧边栏），拼接成完整页面。支持
-Lang en 切换英文组件、-IncludeDrafts
构建草稿、-SkipArchiveRefresh
跳过归档更新。
详细解说 →
rebuild-all.ps1 —— 全站重建
按顺序调用其他脚本，扫描所有博文和独立页面逐个构建。支持
-Force 强制全量、-IncludeDrafts
包含草稿、-Minify
压缩输出。内置增量缓存——对比组件哈希和文件修改时间，跳过未变化的页面。
详细解说 →
generate-archive.ps1 —— 归档 / 标签 / 搜索索引
扫描所有博文元数据（日期、标题、标签、草稿标记），一次扫描产出四种文件：最新文章组件、按年月分组的归档页、标签云页、纯文本搜索索引。支持
-Lang en 生成英文版。
详细解说 →
generate-rss.ps1 —— RSS 订阅源
生成 RSS 2.0 格式的 XML 文件，包含频道描述、文章条目、纯文本摘要和
GUID。输出到 dist/rss.xml。
详细解说 →
generate-sitemap.ps1 —— 站点地图
扫描所有博客、独立页面和静态资源，生成符合 Sitemap Protocol 0.9 的 XML
文件。包含 changefreq（更新频率）和
priority（优先级），跳过草稿页面。当前覆盖约 50 个 URL。
详细解说 →
|
Web 服务器与工具（Python）
web_server.py —— HTTP 服务器
基于 Python 内置
http.server 的自定义 HTTP
服务器。支持白名单路由表（URL → 文件系统路径映射）、CGI
子进程调用、HTTP/1.1 keep-alive、多线程并发、静态资源强缓存、404/403
自定义页面。启动参数：nolog
禁用日志、nocount 禁用访客计数。监听
0.0.0.0:81。
counter.py —— 访客计数器
首页访问时自动递增计数并生成 88×31 像素的 LED 七段数码管动画 GIF。12
帧呼吸动画、扫描线滚动、辉光效果。计数存储在
data/runtime/visitor_count.txt。
mailer.py —— 邮件通知
留言板回复通知的后台发送脚本。由 guestbook.py 以独立子进程调用，读取
SMTP 配置（从环境变量），通过 QQ Foxmail 发送 90s 风格的 HTML
邮件。正文包含回复内容和原留言引用。
banned_words.py —— 屏蔽词模块
从
data/runtime/banned_words.json
读取屏蔽词列表，留言提交时自动将敏感词替换为
***。支持将 JSON 加密为 .dat
文件用于隐私保护（可选）。
mirror-external.py —— 外部资源本地化
扫描组件 HTML 中的外部图片 URL，下载到本地
assets/images/external/
并替换引用路径。用于旧设备 HTTP 访问（无法加载 HTTPS 资源）。支持
--dry-run 预览模式。
generate-emoticons.py —— 表情生成(已废弃)
使用 Pillow 生成 20 枚 20×20 像素风 GIF 表情（em01-em20），输出到
assets/images/emoticons/。
|
CGI 脚本（Python）
guestbook.py —— 留言板
处理留言板表单提交。解析 POST 数据、记录 IP、追加写入 guestbook
文件、提取 @
提及并后台发送邮件通知、触发主页重建。留言写入后自动屏蔽敏感词。
详细解说 →
comments.py —— 文章评论
处理博文评论表单提交。解析 POST 数据、追加写入
data/comments/{slug}.txt、后台异步重建对应博文、302 跳回评论区锚点。支持楼中楼（parent
字段）和 IP 显示开关。
search.py —— 站内搜索
读取搜索索引文件，对关键词执行大小写不敏感全文匹配。标题命中加权，返回带高亮片段的结果页。完全免
JavaScript——一个 HTML 表单提交到 CGI，服务端完成全部逻辑。
editor.py —— Web 编辑器
基于 Web
的博客文章编辑器。支持新建、编辑、删除文章，格式化工具栏（粗体、斜体、链接、图片、脚注、表格），字符计数，实时预览。通过
EDITOR_TOKEN
环境变量控制认证。输出直接写入
src/content/blog/。
toolbox.py —— 90s 工具箱
集成 Base64 编解码、MD5/SHA
哈希计算、时间戳转换、随机密码生成等常用工具。纯 HTML 表单 + CGI
后端，无需 JavaScript。
stats.py —— 访问统计
生成静态统计页面（dist/stats.html）。包含 ASCII 热力图、按小时/天分布、月度趋势、浏览器/OS
分析、User-Agent 考古面板。使用 DB-IP
城市级数据库绘制访客世界地图。支持 .gz 压缩日志读取和本地 IP 过滤。
logger.py —— 统一日志模块
为所有 CGI 脚本提供统一的日志写入接口。按功能分类写入
data/logs/
下的对应文件（guestbook、editor、search、toolbox、error 等）。
|
启动入口
build.cmd — 全站构建入口，内部调用 rebuild-all.ps1
build-draft.cmd — 同上，附加
-IncludeDrafts
start.cmd —
开发服务器启动，预设所有环境变量（SMTP、EDITOR_TOKEN、BANNED_WORDS_KEY），执行
py web_server.py nolog nocount
|
调用顺序
rebuild-all.ps1
内部按以下顺序调用，不需要手动记——但知道这个顺序有助于理解数据流：
|
1
|
generate-archive.ps1
|
扫描元数据 → 最新文章组件 + 归档页 + 标签云 + 搜索索引
|
|
2
|
build.ps1（逐页）
|
拼接组件 → 注入留言/更新日志 → 生成页面
|
|
3
|
generate-rss.ps1
|
生成 RSS 订阅源
|
|
4
|
generate-sitemap.ps1
|
生成站点地图（50+ URL）
|
日常只需要跑
.\scripts\build.cmd（增量）或
powershell .\scripts\rebuild-all.ps1 -Force（全量）。服务器进程
web_server.py
独立运行，不需要随构建重启。
|
|
