每次從零搭一套環(huán)境，我至少要碰四個(gè)文件：docker-compose.yml、nginx.conf、.env，可能還有個(gè)Makefile。改個(gè)端口，漏了同步，系統(tǒng)就悄無聲息地崩掉。我想解決這個(gè)問題。Stage 4A是解法。Stage 4B讓我意識(shí)到解法還不完整。

這篇文章記錄全過程：我怎么做出swiftdeploy，為什么接入Prometheus指標(biāo)和OPA策略邊車，以及當(dāng)我故意破壞自己的金絲雀部署時(shí)，實(shí)際發(fā)生了什么。

核心思路很簡(jiǎn)單。一個(gè)文件——manifest.yaml——掌管所有配置。CLI讀取它，生成nginx.conf和docker-compose.yml。你從不碰生成的文件。要改東西？改manifest，重新跑./swiftdeploy init。

基礎(chǔ)版manifest長(zhǎng)這樣：

services:

image: swiftdeploy-stage4b-app:1.0.0

port: 3000

mode: stable

nginx:

image: nginx:latest

port: 18080

proxy_timeout: 30

network:

name: swiftdeploy-net

driver_type: bridge

./swiftdeploy init讀取這個(gè)文件，用Python的string.Template渲染出兩個(gè)生成文件。模板放在templates/目錄里，包含${VARIABLE}占位符，從manifest上下文替換。config.py的關(guān)鍵代碼：

def render_templates() -> None:

ensure_policy_source()

ctx = manifest_context()

for tmpl_path, out_path in ((NGINX_TMPL, NGINX_OUT), (COMPOSE_TMPL, COMPOSE_OUT)):

rendered = Template(tmpl_path.read_text(encoding="utf-8")).safe_substitute(ctx)

atomic_write(out_path, rendered)

這里用了safe_substitute而不是substitute，因?yàn)楹笳哂龅轿粗?{...}標(biāo)記會(huì)拋異常。nginx配置文件里滿是${request_time}這類變量——如果用substitute，每次渲染都會(huì)炸。safe_substitute把不認(rèn)識(shí)的標(biāo)記原樣保留，nginx拿到它的變量，manifest的值也正確注入。

atomic_write輔助函數(shù)先寫到臨時(shí)文件，再用os.replace覆蓋最終路徑。原因是：如果寫入中途崩潰，你會(huì)得到損壞的配置。os.replace在Python支持的所有操作系統(tǒng)上都是原子操作，所以你要么拿到新文件，要么保留舊文件，絕不會(huì)拿到半個(gè)。

API服務(wù)是個(gè)FastAPI應(yīng)用，三個(gè)端點(diǎn)：GET /返回模式和版本，GET /healthz返回運(yùn)行時(shí)間，POST /chaos用來注入故障（后面細(xì)說）。MODE環(huán)境變量控制應(yīng)用跑在stable還是canary模式——同一份鏡像，不同行為。canary模式下每個(gè)響應(yīng)都帶X-Mode: canary頭。

./swiftdeploy deploy先調(diào)init，然后docker compose up -d，接著每秒輪詢/healthz，直到返回200或60秒超時(shí)。nginx負(fù)責(zé)流量路由。