49 lines
3.0 KiB
Markdown
49 lines
3.0 KiB
Markdown
# Deployment Philosophy Guard: Immutable Configuration Pattern
|
||
|
||
## 原则目标 (Objective)
|
||
在编写 `deploy.sh` 部署脚本或操作服务器环境配置时，彻底避免 `tar` 打包的上下文导致的配置文件覆盖事故。彻底物理阻断**“代码包发布”**与**“生产环境参数”**之间的偶发性交叉。
|
||
|
||
---
|
||
|
||
## 核心漏洞分析 (The "Tar Path Trap")
|
||
在历史上发生的灾难级线上配置丢失案中，部署脚本中常见以下形式的打包语句：
|
||
```bash
|
||
# ❌ 错误示范：致命的 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` 来维护安全，必须从物理架构上进行环境解耦。**
|
||
|
||
1. **环境变量物理隔离（Systemd 级别）**：
|
||
- 所有的环境变量配置文件 `.env` 必须在**代码解压目录的上层目录**或其他专门用于运行时的配置目录。
|
||
- ❌ `EnvironmentFile=/opt/apps/my-agent/backend/.env` (危险)
|
||
- ✅ `EnvironmentFile=/opt/apps/my-agent/.env` (安全)
|
||
|
||
2. **静默失效原则**：
|
||
- 当 `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 ... ]` 存在即跳过的防覆盖保护吗？
|