跳到主要内容
Linux脚本库

贡献指南:提交一个脚本的完整流程

更新于 #贡献指南#投稿#PR#CI#审核

这篇写给想提交脚本的人:什么样的脚本本站会收、什么样的直接拒绝、从 Fork 到 PR 的每一步,以及 CI 和审核会看什么。动手前建议先读一遍脚本开发规范。

适合投稿的脚本

  • 解决具体问题,且在常见发行版上可复现:换源、系统初始化、备份迁移、监控巡检、故障信息采集等;
  • 默认安全:只读,或支持 --dry-run,变更前备份、能回滚;
  • 参数清晰,换一台机器、换一个环境仍能复用;
  • 代码可读,许可证明确,不含密钥、内网地址、个人路径等敏感信息。

明确不接收

下面这些内容不做审核,直接拒绝:

  • 绕过监管或审查的脚本,例如代理搭建、流量伪装、跨境绕过;
  • 破解、授权绕过、激活工具、绕过付费限制;
  • 挖矿、刷量、薅羊毛类脚本;
  • 未授权的扫描、爆破、入侵与提权利用;
  • 窃取凭据、键盘记录、隐私数据回传;
  • 捆绑不可审计的二进制,或从不明地址下载后直接执行;
  • 默认就是破坏性操作、又不提供 --dry-run 的脚本。

只对某一台机器有效、把具体命令硬编码成“参数”、或严重依赖闭源服务的脚本,也暂不接收。

提交流程

  1. Fork 仓库并 clone 到本地。

  2. 新建 src/content/scripts/<slug>/,目录名就是脚本 slug,同时写 script.yaml 与 body/*.sh。字段与写法见脚本开发规范。

  3. 在仓库根目录运行本地自检:

    Terminal window
    node scripts/verify.mjs

    它按 CI 的口径检查脚本定义 schema、预设参数、渲染确定性、危险命令红线与 Shell 语法,并用版本锁确认内容与版本号一致。新增脚本或升版本后如果提示未登记,按提示执行 node scripts/verify.mjs --write 更新版本锁,再跑一次确认通过。改动涉及页面或内容集合时,再跑一次 pnpm build,确认站点能正常构建。

  4. 检查暂存区,确认没有把密钥、服务器地址、个人路径带进来。

  5. 提交 PR,标题写清「新增脚本:xxx」或「修复:xxx」。一次 PR 只做一件事:一个脚本、一个修复或一篇文档,不要把三件事塞进同一个 PR。如果 CI 失败,先按日志在本地复现并修复,不要通过删检查绕过。

  6. PR 描述里写清楚:脚本用途、危险等级与改动路径、是否需要 root/网络、是否幂等、是否支持 --dry-run、在哪些系统与架构上测过、如何回滚、许可证。

CI 会检查什么

  • 构建期 schema:字段范围、分类是否存在、slug 与目录名一致、参数 key 唯一、预设只引用已声明参数且枚举值合法;
  • 危险规则:destructive 必须有 dryRun: true,非只读脚本必须声明 rollback.supported;
  • 渲染:默认参数与每个预设都能渲染成完整脚本,同一组参数每次渲染结果一致;
  • 版本锁:内容变更必须升版本,避免产物地址与内容不一致;
  • shell 静态检查:声明 posix 的脚本不能出现 bash 专属语法,shellcheck 的告警要处理;
  • 容器矩阵:在多个发行版容器里跑参数校验、非法参数、非 root、--dry-run 零写入、连续执行两次无变更等断言;
  • 危险命令扫描:rm -rf /、eval、curl -k、setenforce 0 等会被单独检查;
  • 站点构建:文档 frontmatter 与链接不能把构建搞挂。

审核标准

  • 代码能读懂:命名清楚、有注释,不堆砌一行流命令;
  • 错误处理:失败时给出可读消息和正确退出码,不吞错;
  • 安全默认值:不自动关 SELinux、不默认改防火墙、不静默改 SSH;
  • 可逆:变更前备份,并说明恢复步骤;
  • 兼容声明真实:tested 不要乱标,没测过就如实写未测试;
  • 文档完整:intro、faq、references 该有的有,不夸大效果;
  • 许可证:默认 MIT,引用他人代码要标注来源。

版本与后续维护

已上线脚本的行为发生变化时,应提升 version(语义化版本)并更新 updated,让用户能区分新旧产物;只改注释或文档可以不升。审阅者会按新版本重新跑 CI,合并后站点按新版本重新构建。

相关

本文提到的脚本

输入关键词开始搜索。脚本名、发行版、分类、文档标题都会被索引。

↑↓ 选择 · Enter 打开浏览全部脚本