diff --git a/.env.sample b/.env.sample
index 73e2a61..6e1627b 100644
--- a/.env.sample
+++ b/.env.sample
@@ -218,8 +218,26 @@ WS_AUTH_BEARER_TOKENS=
 # ws_ticket 票据列表（逗号分隔，适合短时授权）
 WS_AUTH_WS_TICKETS=
 
-# ========== 14. 静态资源 CDN（可选） ==========
+# ========== 14. 静态资源 CDN（可选，默认自动 Brotli） ==========
+# auto：优先使用验证通过的 CDN Brotli，其次源站 Brotli/Gzip；off：紧急关闭自动协商
+STATIC_ASSET_COMPRESSION=auto
+# CDN 公网根地址。保留 NUXT_APP_CDN_URL 兼容旧部署；两者都填写时优先使用 STATIC_CDN_BASE_URL。
+STATIC_CDN_BASE_URL=
 NUXT_APP_CDN_URL=
+# 对象存储中的目录前缀；CDN 根地址应直接指向该目录。根目录部署时留空。
+STATIC_CDN_ROOT_PATH=
+# 可选：填写后由 EasyAI 自动发布 canonical、Brotli、Gzip 三套资源。
+# 不填写时只验证客户已有 CDN；验证失败会自动使用源站，不影响 Web 启动。
+# 支持 aliyun、tencent、minio、qiniu、s3Compatible。
+STATIC_CDN_OSS_PROVIDER=
+STATIC_CDN_OSS_ENDPOINT=
+STATIC_CDN_OSS_BUCKET=
+STATIC_CDN_OSS_ACCESS_KEY=
+STATIC_CDN_OSS_SECRET_KEY=
+STATIC_CDN_OSS_REGION=
+STATIC_CDN_OSS_PORT=
+STATIC_CDN_OSS_USE_SSL=true
+STATIC_CDN_FORCE_UPLOAD=false
 
 # ========== 15. 版本 ==========
 VERSION=latest
diff --git a/README.md b/README.md
index 6f44bc1..04b61db 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,12 @@ CONFIG_TRUSTED_PROXY=127.0.0.1,10.0.0.0/8
 
 模板同时为 JSON、CSS、`application/javascript` 和 Nuxt 常用的 `text/javascript` 开启 Gzip；`text/event-stream` 未加入压缩类型，SSE 和 WebSocket 保持流式传输。已经生成的域名配置不会随模板自动更新，旧部署需要手工把 `text/javascript` 加入现有 `gzip_types`，执行 `nginx -t` 成功后再无中断 reload。
 
+前端静态资源默认使用 `STATIC_ASSET_COMPRESSION=auto`。浏览器支持 Brotli 时优先使用经过哈希和响应头验证的 CDN Brotli 资源；客户 CDN 尚未配置编码资源或验证失败时，自动切回 Nuxt 源站的 Brotli/Gzip，不会阻塞 Web 启动。旧部署更新 `docker-compose.yml` 后无需修改 `.env` 即可使用默认值。
+
+私有化客户可继续只配置 `NUXT_APP_CDN_URL`。如果 CDN 已支持 canonical URL 的 Brotli，EasyAI 会自动识别；如果希望 EasyAI 代为发布三套资源，再填写 `.env.sample` 中的 `STATIC_CDN_OSS_*` 最小读写凭据。上传对象使用 `__easyai_encoding/br` 和 `__easyai_encoding/gzip` 固定前缀，并携带正确的 `Content-Encoding`。也可由客户自己的流水线按该目录协议上传，EasyAI只负责验证。紧急回退可设置 `STATIC_ASSET_COMPRESSION=off`。
+
+CDN 验证结果保存在 `./data/cdn-init`，并与当前前端构建标识绑定；升级后旧结果会被忽略。任何密钥都只应放在本机 `.env` 或安全配置中心，不要提交到仓库。
+
 `https.sh` 单独执行时也可以跳过域名选择：
 
 ```bash
diff --git a/docker-compose.yml b/docker-compose.yml
index 1fa0933..b15cb08 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -26,8 +26,13 @@ services:
       # 默认的服务器websocket地址，本地不需要更改，云服务需要修改为云端IP，并放行对应端口
       - NUXT_PUBLIC_BASE_SOCKETURL=${NUXT_PUBLIC_BASE_SOCKETURL}
       - NUXT_APP_CDN_URL=${NUXT_APP_CDN_URL}
+      # 默认自动选择 CDN Brotli；CDN 不兼容时安全回退到源站预压缩资源
+      - STATIC_ASSET_COMPRESSION=${STATIC_ASSET_COMPRESSION:-auto}
       # Agent 服务治理 API 地址（前端直接调用，走 Nginx 代理时配置为 /asg-api）
       - NUXT_PUBLIC_SG_APIURL=${NUXT_PUBLIC_SG_APIURL}
+    volumes:
+      # 保存与当前前端构建绑定的 CDN 验证结果，旧结果不会跨构建误用
+      - ./data/cdn-init:/tmp/cdn-init
     # 日志大小设置，避免日志文件过大
     env_file:
       - .env