Deployment Philosophy Guard: Immutable Configuration Pattern

原则目标 (Objective)

在编写 deploy.sh 部署脚本或操作服务器环境配置时，彻底避免 tar 打包的上下文导致的配置文件覆盖事故。彻底物理阻断**“代码包发布”与“生产环境参数”**之间的偶发性交叉。

核心漏洞分析 (The "Tar Path Trap")

在历史上发生的灾难级线上配置丢失案中，部署脚本中常见以下形式的打包语句：

# ❌ 错误示范：致命的 tar 路径陷阱
tar czf backend.tar.gz --exclude='backend/.env' -C backend .

原因解析： 由于使用了 -C backend . 指令，tar 的作用域已经全盘切换至 backend 目录下。此时 .env 文件的相对路径变成了 ./.env，而 --exclude='backend/.env' 变得形同虚设！结果是：开发者本地带有大量 dev_user_001 等测试占位符的 .env 会被强制打包进 .tar.gz 中，在远端 tar xzf 解压时，产生毁灭性的生产环境覆盖。

运维铁律 (Systemd & Environment Boundary)

禁止仅仅依靠 --exclude 来维护安全，必须从物理架构上进行环境解耦。

环境变量物理隔离（Systemd 级别）：
- 所有的环境变量配置文件 .env 必须在代码解压目录的上层目录或其他专门用于运行时的配置目录。
- ❌ EnvironmentFile=/opt/apps/my-agent/backend/.env (危险)
- ✅ EnvironmentFile=/opt/apps/my-agent/.env (安全)
静默失效原则：
- 当 EnvironmentFile 被定位到代码目录之外，意味着无论部署脚本在后续执行 tar xz 时是否不小心夹带了开发版 .env 放进 my-agent/backend/ 中，systemd 都将对那堆错误文件置若罔闻。这使得错误打包本身自动降维成为无影响的“垃圾文件”。

反面模式 (Anti-Patterns)

❌ 禁止模式 (Anti-pattern)	✅ 推荐模式 (Best Practice)	理由
修改 Systemd 指向代码解压目录下的 `.env`	Systemd 指向工程根目录或 `/etc/` 等专用配置目录的 `.env`	防止发版引起生产配置丢失
服务器脚本中用 `sed -i` 试图修补上传的 `.env`	部署脚本在判断父目录 `.env` 不存在时才提供空模板，有则不碰	防止覆盖，保证配置只进行增量挂载
在自动化部署脚本中试图把 `keys` 写死	SSH 下发命令在控制台提醒：`"请手动编辑上一层目录的 .env"`	`BYOK` 原则与安全交接

出发前自检 (Checklist)

当你修改或新建类似 deploy_*.sh 或编写 .service 注册脚本时，请进行下述三项灵魂拷问：

当前的 tar --exclude 是否和 -C 标签出现了上下文冲突？
脚本或服务中指向的 .env 路径属于不被代码包直接覆盖的独立目录吗？
服务器初始化脚本如果写入 cat > .../.env，外面有包一层 if [ ! -f ... ] 存在即跳过的防覆盖保护吗？

3.0 KiB Raw Permalink Blame History Unescape Escape