为开源准备一个项目：README、LICENSE 与最小可复现

把博客的几个仓库开源后，我最大的体会是：开源不是「把代码设成 public」那一下，而是让别人真的能看懂、能跑起来。 代码只是地基，README、LICENSE、可复现的启动路径才是让项目「可被使用」的部分。

一、先做密钥治理（前置）

这是开源前不可跳过的第一步：扫描密钥、清理历史、轮换凭证。详见我另一篇《开源前的密钥治理》。一句话——进过 git 历史的密钥都当泄露处理。这一步没做完，后面都不用谈。

二、README：让人 5 分钟跑起来

一份好的 README 不是功能罗列，而是回答读者的几个问题：

这是什么、解决什么（一段话讲清定位）；
架构长什么样（一张图胜过千言，我用 mermaid 画服务拓扑）；
怎么跑起来（最重要——给出可复制粘贴的最小命令）；
怎么配置（环境变量清单 + 哪些是密钥）；
相关仓库（多仓库项目要互相链接）。

「怎么跑起来」要做到可复制粘贴：

git clone https://github.com/zzlw/andy-blog-deploy
cd andy-blog-deploy
cp .env.development .env        # 全是安全的本地默认值
make dev                        # 一键拉起全部服务

如果读者照着敲完跑不起来，README 就失败了。所以这几行命令我是真的在干净环境里跑过一遍才写进去的。

三、双语 README 的取舍

我给部署仓库写了中英两版（README.md 英文默认 + README.zh-CN.md）。取舍是：英文做默认，覆盖最广的读者；中文同步一份，方便中文读者。两份顶部互相链接，谁也别落下。要点是内容对齐——别让两份说的不一样，那比只有一份还糟。

四、LICENSE：别让人猜

没有 LICENSE 的「开源」其实不是开源——默认版权全保留，别人法律上不能用。所以一定要放一个明确的 LICENSE 文件。个人项目我用 MIT：宽松、好理解、对使用者友好：

MIT License
Copyright (c) 2026 Gavin
Permission is hereby granted, free of charge, to any person obtaining a copy...

README 里引用到 LICENSE 时，确保文件真的存在——我就犯过「README 提了 LICENSE 但文件没建」的低级错，补上才算闭环。

五、最小可复现：开源的硬通货

「最小可复现」意味着：一个陌生人，不问你任何问题，就能把项目跑起来。它依赖几件事：

配置示例齐全：.env.development 提供全套安全默认值（本地 MinIO、占位密钥），不依赖任何外部账号就能起；
一键启动：用 make 或 compose 把多步操作收成一条命令；
依赖自包含：数据库、缓存、对象存储都用容器拉起，不要求读者「先去装个 MongoDB」；
占位密钥写清楚：像 JWT_SECRET=dev_only_jwt_secret_please_change 这种，名字本身就告诉人「这是开发占位，生产请替换」。

可复现性是开源项目的硬通货——它直接决定别人会 star 收藏吃灰，还是真的 clone 来用。

六、给「可选功能」留开关

开源项目的读者环境千差万别。像 AI 服务这种依赖外部账号的功能，我做成可选：地址没配就不启用、不渲染入口。这样没有 Cloudflare 账号的人也能把博客主体跑起来，不会卡在「必须先有某个云服务」。降低门槛，就是降低别人放弃的概率。

小结

开源一个项目的清单：① 密钥治理（扫描/清史/轮换）→ ② 能 5 分钟跑起来的 README → ③ 对齐的双语文档 → ④ 明确的 LICENSE → ⑤ clone 即复现的最小启动路径 → ⑥ 给可选功能留开关。代码是地基，但让项目「可被别人使用」的，是这些围绕代码的诚意。