# 用 PowerShell 把本地文本“自动投递”到 Typecho：auto-upload-watch.ps1 实战

最近把笔记、片段、日志分散在各个目录里，手动复制到后台发布不仅麻烦，还容易忘。于是写了个小工具：一个纯 PowerShell 的“自动投递脚本”，把指定文件夹里的文本文件按顺序发布到 Typecho，并在成功后归档。脚本名叫：auto-upload-watch.ps1。

这篇日志会从动机、功能、设计、实现细节到部署运维，完整讲解这段代码。你可以直接拿走脚本，改改配置就能跑起来。

------

## 目标与场景

- 把 D:\website-files\upload_file 下的文本文件自动发布到 Typecho。
- 文件按创建时间依次投递，先到先发。
- 标题自动带上相对路径前缀，天然做层级归纳（如 c8-20251031_002439|064_caesar_full_flag）。
- 成功后把源文件移动到 D:\website-files\upload_completed\yyyy-MM-dd，便于留痕与审计。
- 可一次性跑完退出，也可常驻后台每 30 秒轮询新文件。
- 支持多种纯文本扩展名，容错不同编码（UTF-8 优先，失败回退到 GBK 等）。

适用人群：

- 想把本地目录当“离线稿箱”，定期自动发博客。
- 从其他系统导出的文本要批量迁移到 Typecho。
- 做自动化抓取/笔记整理后，让机器代发文章。

------

## 功能总览

- 文件扫描与过滤
- 递归扫描 upload_file
- 过滤隐藏/系统文件
- 只处理白名单后缀（.txt/.md/.html/...）
- 按 CreationTimeUtc → LastWriteTimeUtc 排序
- 标题与内容
- 标题可取文件名（默认）或正文第一行
- 自动生成路径前缀作为标题前缀，用 | 连接层级
- 可选在正文顶部插入来源路径提示 [source] 相对路径|文件名
- 支持内容长度截断（默认不截断）
- Typecho 发布
- 使用 XML-RPC 接口 metaWeblog.newPost
- 支持默认分类/标签、是否立即发布
- 自动尝试 /action/xmlrpc 与 /index.php/action/xmlrpc 两种端点
- 返回 Post ID，失败捕获 Fault 码
- 归档与清理
- 发布成功后移动到 upload_completed/日期
- 重名则自动追加时间戳避免覆盖
- 每轮结束清理 upload_file 内的空子目录
- 全程日志记录到 auto-upload.log
- 运行模式
- RunOnce=$true 扫一次退出
- RunOnce=$false 常驻轮询（默认 30s）

------

## 关键设计细节

1. 端点自修复
很多站点启用了伪静态或不同入口，直接打 /action/xmlrpc 可能被 CDN/WAF 拦截。脚本会先探测原端点；失败时自动切换到 /index.php/action/xmlrpc 再测一次。并检测返回是否是 HTML（常见于被拦截时返回防火墙页）。
2. 编码容错
Read-TextFileSmart 先用 UTF-8 读，失败再用 FallbackEncoding（默认 936=GBK），最后尝试 Get-Content，尽量不因编码问题中断。
3. 安全与可运维性

- 账号明文存在脚本里：必须依赖文件权限控制（NTFS ACL）。建议仅服务账户可读。
- 请求强制 TLS1.2，带自定义 UA，便于后端日志分流。
- 所有动作写入日志文件，出错也尽量不中断整批任务。
- 仅成功发布才归档；失败的文件留在待处理目录以便重试或人工排查。

1. 路径即分类思路
Make-RelPathPrefix 会把 upload_file 相对路径的目录结构用 | 串起来，加到标题前缀里。
例：D:\website-files\upload_file\c8\20251031_002439\064_caesar_full_flag.md
标题将是：c8|20251031_002439|064_caesar_full_flag
这让你无需手动分门别类，靠目录组织即可。

------

## 配置说明

脚本顶部是内置配置，按需调整：

- TypechoConfig.Endpoint：你的 Typecho XML-RPC 端点
- User/Pass/BlogId：API 认证信息
- DefaultCategories/DefaultTags：默认分类与标签
- PublishNow：true 立即发布；false 存草稿
- TitleFromFilename：true 标题取文件名；false 取正文首行
- FallbackEncoding：读取失败时备用编码（936=GBK）
- MaxContentLength：0 不截断；>0 限制正文长度
- AllowedExtensions：允许的文件后缀
- UploadDir/CompletedDir/LogFile：三个关键目录/日志路径
- RunOnce：一次性 vs 常驻
- PollInterval：轮询间隔秒数

建议：

- 生产环境把脚本放到仅当前账户可读的目录，给日志和完成目录设置合理 ACL。
- 如果站点带鉴权层、CDN 白名单，先放通脚本所在机器的出口 IP。

------

## 发布流程（核心调用链）

- Process-Once
- Prepare-Endpoint → Test-TypechoXmlRpc → 端点可用性、鉴权校验
- Pick-PendingFiles → 取待发文件列表
- 对每个文件：
- Publish-OneFile
- Read-TextFileSmart → 内容与编码处理
- Make-TitleFromPath / 首行标题
- 可选插入 [source]
- Publish-TypechoPost → 发送 metaWeblog.newPost
- Move-ToCompleted → 成功后归档到按日目录
- Remove-EmptySubDirs → 清理空文件夹
- 主循环
- RunOnce=true：跑一次退出
- RunOnce=false：while(true) → Process-Once → Sleep(PollInterval)

------

## XML-RPC 实现要点

- 调用 metaWeblog.getRecentPosts 做连通与鉴权测试。
- 发布使用 metaWeblog.newPost，传入 title、description、categories、mt_keywords。
- 返回值兼容数字 ID 或字符串 ID。
- Parse-Fault 解析 faults，遇到 Fault 抛出异常，日志记录后跳过文件。

如果你的 Typecho 安装对 XML-RPC 有插件级定制，注意接口兼容性；若返回 HTML，通常是中间层拦截或 302 跳转到了登录页/防火墙页。

------

## 部署与运行

- Windows 10/11 或 Server，PowerShell 5.1+ 即可；PowerShell 7 也兼容。
- 首次运行：
1. 编辑脚本配置，填好 Endpoint/User/Pass。
2. 运行权限：右键 PowerShell 以管理员或有权账户执行，确保脚本、目录可写。
3. 双击或在 PowerShell 执行：.\auto-upload-watch.ps1
4. 查看日志：D:\website-files\auto-upload.log
- 作为“服务化”运行：
- 用计划任务（Task Scheduler）开机启动，勾选“无论用户是否登录都要运行”
- 或用 NSSM/WinSW 包装成 Windows Service，指向 powershell.exe -File …。
- 生产建议固定 PollInterval 为 15~60 秒，避免高频拉取。

------

## 日常使用建议

- 在 upload_file 下建层级目录，按主题/日期组织。文件名即标题主体。
- 如果想保留来源线索，保持 [source] 提示开启；不需要就注释掉相关 4 行。
- 若内容经常是 GBK，考虑把 FallbackEncoding 改为 65001 以外的合适编码，或统一保存为 UTF-8 无 BOM。
- 大批量导入时先设 PublishNow=false，人工在后台抽查无误后统一改为发布。
- 失败文件会原地保留。根据日志“发布失败”记录的 Fault 信息排查。

------

## 常见问题排查

- 返回 HTML 或 403/5xx：检查 CDN/WAF，放通 XML-RPC；或使用 /index.php/action/xmlrpc。
- Fault 401/403：账号/密码错误，或账户权限不足。
- 发布慢/超时：服务器限流、网络抖动。可调大 TimeoutSec 或降低 PollInterval 并分批投递。
- 中文乱码：源文件编码不一致；统一 UTF-8，或调整 FallbackEncoding。
- 重复发布：目录里同一文件被重复生成。建议上游生成侧用唯一文件名，或在完成目录做审计。

------

## 小结

这份 auto-upload-watch.ps1 把“文件夹即投稿箱”的思路落地到 Typecho：

- 简单、可审计、可回滚
- 低耦合，不侵入主题和后台
- 生产可用的日志、容错与归档策略

如果你也想把写作流程自动化，不妨先在测试站点跑一圈，再迁移到正式环境。欢迎按需改造，比如：

- 从目录层级映射到 Typecho 分类
- 从文件内 YAML Front Matter 读取标签/分类/发布时间
- 支持图片/附件上传并重写正文链接

有问题或想法，留言交流。