Shell脚本自动创建Wiki页面并归档日志：运维知识沉淀实战

1. 从一个运维夜班场景说起：为什么要用脚本自动建Wiki页面

凌晨两点被告警叫醒，某台边缘节点的磁盘水位又飙了。你登上跳板机，一通排查之后定位到是某个日志轮转策略没生效，旧日志把分区塞满了。清理完毕，顺手把排查过程记到了团队Wiki上——这已经是这个月第三次因为同类问题半夜爬起来。问题不在于排查本身有多难，而在于每次排查完的日志证据、处理动作、根因结论都散落在聊天记录和终端回滚缓冲里，下次换个人值班，又得从头捋一遍。

这就是"通过shell创建Wiki里的页面，并把日志文件的内容贴进去"这个需求真正要解决的痛点。它听起来像是个小工具，实际上是把故障排查的现场证据和知识库沉淀这两件本来割裂的事情，用一条脚本串了起来。核心逻辑很朴素：脚本读取本地日志文件，调用Wiki系统提供的接口，自动创建一个新页面，把日志内容作为页面正文写进去。但真动手做的时候，你会发现坑比想象中多——接口鉴权怎么处理、日志里的特殊字符怎么转义、页面标题怎么保证唯一、大文件怎么分块、失败重试怎么做，每一个都能让你在凌晨三点骂出声。

这篇文章适合三类人看：一是经常需要把排查记录归档的运维和SRE；二是想给团队搭一套自动化知识沉淀流程的技术负责人；三是单纯想学shell调用HTTP接口这门手艺的开发者。我会从接口选型讲到脚本落地，把每一步的"为什么"都掰开说清楚，最后附上我踩过的几个真实坑。全程不依赖任何特定厂商的私有工具，思路通用，你换成自己团队的Wiki系统照样能套。

2. 先搞清楚你的Wiki到底提供了哪种写入通道

动手写脚本之前，最忌讳的就是直接开干。你得先确认目标Wiki系统对外暴露了什么能力。市面上的Wiki系统大致分三类写入通道，选错了后面全是返工。

2.1 三类常见接口形态的对比与取舍

第一类是REST API，这是最理想的。绝大多数现代Wiki系统都会提供基于HTTP的接口，通常用POST创建页面、PUT更新页面，鉴权走Token或者Basic Auth。它的好处是语义清晰、返回结构化数据（一般是JSON）、错误码规范，脚本里用curl就能搞定，不需要额外依赖。

第二类是命令行工具（CLI）。有些Wiki系统自带官方CLI，比如某些基于Git的Wiki会提供命令行客户端。这类工具的好处是帮你封装了鉴权，坏处是版本兼容性差，换台机器可能就跑不起来，而且输出格式不一定是机器友好的。

第三类是直接操作底层存储。比如Wiki底层是文件系统或者Git仓库，你直接往对应目录写Markdown文件。这种方式最"暴力"，但风险也最高——绕过了应用层的校验和索引更新，可能导致页面创建了但搜不到，或者触发缓存不一致。

我的建议很明确：优先找REST API。如果官方文档里找不到，就去翻它的开发者页面或者抓一次网页端创建页面的请求，通常能反推出接口地址和参数格式。这一步花半小时，能省后面几小时的调试。

2.2 鉴权方式决定了脚本的安全边界

确认了接口，接下来是鉴权。常见的有三种：API Token、Basic Auth（用户名密码）、OAuth。Token最省事，一般放在请求头里，比如Authorization: Bearer xxxxx。Basic Auth稍微麻烦点，需要把用户名密码做Base64编码。OAuth最复杂，涉及令牌刷新，一般脚本里不太愿意碰。

这里有个关键决策点：凭证绝对不能硬编码在脚本里。我见过太多人图省事，直接把Token写死在shell脚本第一行，然后这个脚本被提交到了代码仓库，Token就这么泄露了。正确做法是把凭证放在环境变量或者独立的配置文件里，脚本运行时读取，并且给配置文件设好权限（比如chmod 600）。

# 从环境变量读取，而不是硬编码 WIKI_TOKEN="${WIKI_API_TOKEN:?请先设置WIKI_API_TOKEN环境变量}" WIKI_BASE="https://your-wiki-host/api/v1"

${VAR:?message}这个写法很实用，变量没设置时脚本会直接报错退出，避免带着空Token去请求接口，返回一堆看不懂的401。

2.3 页面创建接口的请求体长什么样

不同Wiki系统的请求体字段名不一样，但核心字段就那么几个：空间/路径（space/path）、标题（title）、正文（content/body）、父页面（parent）。以常见的JSON格式为例，大致是这样：

{ "space": "OPS", "title": "节点磁盘告警排查-20240520", "parent_id": "123456", "body": { "storage": "storage_format", "value": "这里是日志内容" } }

你要做的是对照官方文档，把字段名替换成你系统的实际字段。有个小技巧：先在网页端手动创建一个测试页面，然后用浏览器开发者工具看创建请求的Payload，照着抄最准。文档经常滞后于实际接口，抓包才是真相。

3. 日志内容塞进页面的三个技术难点

接口通了不代表事情就成了。日志文件这东西，天生就是"脏"的——里面有各种特殊字符、超长行、二进制片段，直接往JSON里塞，十有八九会出问题。这一章专门讲怎么把日志安全地"搬运"到页面正文里。

3.1 JSON转义：为什么你的请求总是400

日志里最常见的"杀手"是双引号和反斜杠。JSON规范要求字符串里的双引号必须转义成\"，反斜杠要转义成\\。日志里如果有一行path="C:\Users\test"，你不做处理直接拼进JSON，接口返回的必然是400 Bad Request，而且错误信息往往含糊其辞，让你怀疑人生。

手动转义容易漏，正确做法是用工具生成JSON。jq是shell里处理JSON的瑞士军刀，它有个-Rs参数能把原始文本安全地转成JSON字符串：

# 把日志文件内容安全转义成JSON字符串 LOG_CONTENT=$(jq -Rs . < /var/log/app/error.log) # 构造完整请求体 PAYLOAD=$(jq -n \ --arg title "$PAGE_TITLE" \ --argjson body "$LOG_CONTENT" \ '{title: $title, body: {storage: "storage_format", value: $body}}')

jq -Rs .会把整个文件读成一行字符串并做完整转义，jq -n负责拼装对象。这样生成的JSON是100%合法的，不用你操心任何转义细节。如果系统里没有jq，那就得用python3 -c或者sed手动处理，但强烈建议装个jq，它是运维脚本的标配。

3.2 大文件处理：一次性塞进去会超时

日志文件动辄几十兆，你不可能把整个文件塞进一个请求体。接口一般都有大小限制（常见是1MB到10MB），超了直接拒绝。这时候有两个策略：截取关键片段或者分块追加。

截取片段更实用。排查日志时，真正有价值的就是报错前后的那几百行。用tail或者grep -A -B提取上下文：

# 提取最后500行，并带上时间戳标记 { echo "=== 日志片段（最后500行）===" echo "" tail -n 500 /var/log/app/error.log } > /tmp/log_snippet.txt

如果确实需要完整日志，那就分块。先创建页面写入第一块，然后调用更新接口逐块追加。但要注意，追加操作需要先获取页面当前版本号（version），否则会触发编辑冲突。这个逻辑比较复杂，一般场景下截取片段就够了。

3.3 代码块包裹：让日志在页面上可读

日志直接贴进页面，格式会乱成一团。正确的做法是用Wiki支持的代码块语法把日志包起来。大多数Wiki支持Markdown的围栏代码块：

# 用代码块包裹日志内容 { echo '```log' cat /tmp/log_snippet.txt echo '```' } > /tmp/log_block.txt

这样在页面上日志会以等宽字体显示，保留原始缩进，可读性大幅提升。如果你的Wiki用的是富文本存储格式（比如某些系统存的是HTML），那就得用对应的<pre>标签或者它自己的宏语法。这一步一定要在网页端手动验证一次，确认渲染效果符合预期，再写进脚本。

注意：日志里如果本身包含三个反引号，会提前闭合代码块，导致后面的内容格式错乱。稳妥起见，可以在包裹前把日志里的反引号替换掉，或者用四个反引号作为围栏。

4. 把脚本拼起来：从读取日志到页面落地的完整链路

前面铺垫了这么多，现在到了真正组装脚本的环节。我会把整个流程拆成几个函数，每个函数只干一件事，这样调试起来方便，出问题也能快速定位是哪一环。

4.1 参数校验与变量准备

脚本的第一段永远是参数校验。别嫌烦，这一步能挡掉80%的低级错误。

#!/usr/bin/env bash set -euo pipefail # 用法：./create_wiki_page.sh <日志文件路径> <页面标题> LOG_FILE="${1:-}" PAGE_TITLE="${2:-}" if [[ -z "$LOG_FILE" || -z "$PAGE_TITLE" ]]; then echo "用法: $0 <日志文件路径> <页面标题>" >&2 exit 1 fi if [[ ! -f "$LOG_FILE" ]]; then echo "错误: 日志文件不存在: $LOG_FILE" >&2 exit 1 fi WIKI_BASE="${WIKI_BASE_URL:?请设置WIKI_BASE_URL}" WIKI_TOKEN="${WIKI_API_TOKEN:?请设置WIKI_API_TOKEN}"

set -euo pipefail这三件套是shell脚本的安全带：-e遇到错误立即退出，-u使用未定义变量报错，-o pipefail管道中任一环节失败就整体失败。没有这三行，脚本会在出错后继续往下跑，产生一堆莫名其妙的副作用。

4.2 日志预处理与内容组装

接下来处理日志内容。我习惯把预处理逻辑单独抽出来，方便复用和测试。

prepare_content() { local log_file="$1" local tmp_out tmp_out=$(mktemp) { echo "## 日志摘要" echo "" echo "- 来源文件: $(basename "$log_file")" echo "- 采集时间: $(date '+%Y-%m-%d %H:%M:%S')" echo "- 文件大小: $(du -h "$log_file" | cut -f1)" echo "" echo "## 日志内容" echo "" echo '```log' tail -n 500 "$log_file" echo '```' } > "$tmp_out" echo "$tmp_out" }

这个函数做了几件事：加了元信息头部（来源、时间、大小），方便日后追溯；用代码块包裹日志正文；只取最后500行控制体积。mktemp生成临时文件，避免污染当前目录。用完记得清理，可以在脚本末尾加trap 'rm -f "$tmp_out"' EXIT。

4.3 调用接口与错误处理

核心的请求函数，用curl发POST。这里的关键是把HTTP状态码和响应体分开处理，不能只看curl的退出码。

create_page() { local title="$1" local content_file="$2" local body body=$(jq -n \ --arg title "$title" \ --rawfile content "$content_file" \ '{title: $title, body: {storage: "storage_format", value: $content}}') local response http_code response=$(curl -sS -w '\n%{http_code}' \ -X POST "${WIKI_BASE}/pages" \ -H "Authorization: Bearer ${WIKI_TOKEN}" \ -H "Content-Type: application/json" \ -d "$body") http_code=$(echo "$response" | tail -n1) local resp_body resp_body=$(echo "$response" | sed '$d') if [[ "$http_code" -ge 200 && "$http_code" -lt 300 ]]; then echo "页面创建成功: $title" echo "$resp_body" | jq -r '.url // empty' else echo "页面创建失败，HTTP状态码: $http_code" >&2 echo "$resp_body" >&2 return 1 fi }

-w '\n%{http_code}'让curl在响应体末尾追加状态码，然后用tail -n1和sed '$d'把两者分离。这个技巧比单独发一次HEAD请求要高效，也比解析curl的-i输出更干净。--rawfile是jq读取文件的参数，比--arg更适合大文本，因为它不做shell层面的转义。

4.4 主流程串联与退出码约定

最后把函数串起来，加上重试逻辑。

main() { local content_file content_file=$(prepare_content "$LOG_FILE") trap 'rm -f "$content_file"' EXIT local attempt=1 local max_attempts=3 while [[ $attempt -le $max_attempts ]]; do if create_page "$PAGE_TITLE" "$content_file"; then exit 0 fi echo "第 ${attempt} 次尝试失败，等待重试..." >&2 sleep $((attempt * 2)) attempt=$((attempt + 1)) done echo "重试 ${max_attempts} 次后仍然失败" >&2 exit 1 } main

重试间隔用attempt * 2做退避，避免接口临时抖动时疯狂重试把对方打挂。退出码约定：0成功，1失败，这样上层调度系统（比如cron或者CI）能正确判断执行结果。

5. 那些文档里不会写的踩坑记录

脚本能跑通只是及格线，真正让你在半夜不翻车的，是这些血泪教训。

5.1 页面标题重复导致的静默覆盖

我第一次上线这个脚本时，标题用的是固定的"磁盘告警排查记录"。结果第二次运行，接口返回200，我以为成功了，打开Wiki一看——旧页面被覆盖了，第一次的日志全没了。原因是很多Wiki系统的创建接口在标题重复时会执行"更新"而非"报错"。

解决办法是给标题加唯一后缀，用时间戳或者日志文件的哈希值：

PAGE_TITLE="磁盘告警排查-$(date '+%Y%m%d-%H%M%S')" # 或者用文件内容哈希 PAGE_TITLE="磁盘告警排查-$(md5sum "$LOG_FILE" | cut -c1-8)"

时间戳适合按时间归档，哈希适合去重（同一份日志不会重复建页）。选哪种取决于你的归档策略。

5.2 特殊字符在URL路径里的坑

有些Wiki的接口把页面路径放在URL里，比如/pages/OPS/磁盘告警。中文和空格在URL里必须做百分号编码，否则请求直接404。用jq的@uri过滤器或者python3 -c "import urllib.parse; print(urllib.parse.quote('...'))"都能处理。我吃过一次亏，标题里带了个斜杠，结果被解析成了路径分隔符，页面建到了错误的层级下。

5.3 Token过期与时钟偏移

Token一般都有有效期。如果你的脚本是定时任务，某天突然全部失败，第一反应应该是查Token是不是过期了。另外，如果服务器时钟和认证服务器偏差太大（超过几分钟），基于时间戳的签名鉴权会直接失败。用ntpdate或者chronyd保证时钟同步，这个坑很隐蔽，排查起来能耗掉一晚上。

5.4 日志文件正在被写入时的读取问题

如果日志文件正在被其他进程写入，你cat的时候可能读到半行，或者文件被轮转（rotate）后你读的是旧inode。稳妥做法是先复制一份快照再处理：

cp "$LOG_FILE" /tmp/log_snapshot_$$.txt

或者用tail -n 500这种只读末尾的方式，受影响较小。如果日志轮转频繁，建议在脚本里判断文件是否被替换（比较inode），必要时重新打开。

6. 让这套流程真正融入日常运维

脚本写完不是终点，怎么让它稳定运行、真正减轻负担，才是要考虑的。

6.1 触发方式的选择：手动、定时还是事件驱动

最简单的触发是手动执行，排查完顺手跑一下。进阶一点是定时任务，比如每天凌晨把当天的错误日志汇总成一个页面。最理想的是事件驱动——监控系统检测到告警时自动触发脚本，把现场日志直接归档。三种方式可以并存，手动用于临时排查，定时用于日常归档，事件驱动用于紧急故障。

用cron做定时任务时，记得把环境变量在crontab里显式声明，因为cron的环境和你登录shell的环境不一样，WIKI_API_TOKEN这类变量不会自动继承：

# crontab 示例 0 3 * * * WIKI_API_TOKEN=xxx WIKI_BASE_URL=https://wiki.example.com/api /opt/scripts/create_wiki_page.sh /var/log/app/error.log "每日错误日志归档-$(date +\%Y\%m\%d)"

注意cron里%需要转义成\%，这是个经典坑。

6.2 日志归档页面的组织策略

页面建多了会乱。建议按"空间/年份/月份"的层级组织，父页面ID在脚本里作为参数传入。这样一年下来，Wiki里会形成一个清晰的时间线，回溯问题时按时间翻就行。另外，可以在页面里加上标签（tag），比如告警、磁盘、节点A，方便后续用标签检索。

6.3 失败告警与可观测性

脚本自己失败了，你得知道。最简单的做法是在失败分支里发一封邮件或者一条IM消息。更进一步，可以把每次执行的结果（成功/失败、耗时、页面URL）写到一个本地日志里，定期检查失败率。别让自动化脚本变成"沉默的哑巴"，出了问题没人知道，比没有脚本还糟糕。

6.4 权限最小化与审计

给脚本用的Token，权限要尽可能小——只给创建页面和更新页面的权限，不要给删除权限。万一Token泄露，损失可控。另外，Wiki系统一般都有操作审计日志，定期看一眼脚本账号的操作记录，确认没有异常创建。

我个人在实际操作中的体会是，这套脚本最大的价值不在于省了那几分钟手动复制粘贴的时间，而在于它强制你把"排查"和"记录"绑定在了一起。以前排查完就关终端，现在脚本一跑，知识就沉淀下来了。团队里新人遇到同类问题，搜一下Wiki就能找到历史现场，这才是自动化真正的复利。最后分享一个小技巧：在脚本里加一个--dry-run参数，只打印将要发送的请求体而不真正发送，调试阶段能帮你省下大量来回试错的时间。