V1

基于當(dāng)前項(xiàng)目結(jié)構(gòu)，Docker 交付和在線升級(jí)計(jì)劃如下：

Docker 交付與在線升級(jí)方案

一、總體架構(gòu)設(shè)計(jì)

1.1 容器化策略

• 應(yīng)用鏡像：為 FastAPI 主應(yīng)用構(gòu)建獨(dú)立 Docker 鏡像

• 服務(wù)編排：使用 Docker Compose 編排所有服務(wù)

• 數(shù)據(jù)持久化：數(shù)據(jù)庫、配置文件、日志等使用 Volume 持久化

• 多環(huán)境支持：開發(fā)、測試、生產(chǎn)環(huán)境使用不同的 Compose 文件

1.2 版本管理策略

• 鏡像標(biāo)簽：使用語義化版本（如 v1.0.0）和 Git Commit SHA（如 v1.0.0-abc1234）

• 版本標(biāo)識(shí)：在鏡像內(nèi)記錄版本信息，便于運(yùn)行時(shí)查詢

• 回滾機(jī)制：保留歷史鏡像，支持快速回滾

二、Docker 文件結(jié)構(gòu)規(guī)劃

aixx/
├── docker/
│   ├── compose.yml              # 開發(fā)環(huán)境（已有）
│   ├── compose.prod.yml         # 生產(chǎn)環(huán)境編排文件（新建）
│   ├── Dockerfile               # 應(yīng)用鏡像構(gòu)建文件（新建）
│   ├── Dockerfile.multi-stage   # 多階段構(gòu)建優(yōu)化版（可選）
│   ├── .dockerignore            # Docker 構(gòu)建忽略文件（新建）
│   ├── docker-entrypoint.sh     # 容器啟動(dòng)腳本（新建）
│   ├── upgrade.sh               # 升級(jí)腳本（新建）
│   └── healthcheck.sh            # 健康檢查腳本（新建）
├── deployment/
│   ├── docker-compose.prod.yml  # 客戶交付用生產(chǎn)配置（新建）
│   ├── .env.example             # 環(huán)境變量模板（新建）
│   ├── upgrade/                 # 升級(jí)相關(guān)腳本
│   │   ├── upgrade.sh           # 主升級(jí)腳本
│   │   ├── rollback.sh          # 回滾腳本
│   │   └── check-version.sh     # 版本檢查腳本
│   └── scripts/                 # 部署輔助腳本
│       ├── init.sh              # 初始化腳本
│       └── backup.sh            # 備份腳本
└── docker/
    └── [現(xiàn)有文件保持不變]

三、具體實(shí)施方案

3.1 Dockerfile 設(shè)計(jì)要點(diǎn)

• 基礎(chǔ)鏡像：使用 Python 3.11 slim 鏡像

• 構(gòu)建優(yōu)化：

  • 多階段構(gòu)建減少鏡像體積

  • 使用 uv 進(jìn)行依賴安裝

  • 分層緩存優(yōu)化（依賴與代碼分離）

• 安全：

  • 非 root 用戶運(yùn)行

  • 最小權(quán)限原則

• 版本注入：構(gòu)建時(shí)注入版本信息到鏡像

3.2 Docker Compose 生產(chǎn)配置要點(diǎn)

• 網(wǎng)絡(luò)：使用自定義網(wǎng)絡(luò)隔離

• 健康檢查：所有服務(wù)配置健康檢查

• 資源限制：CPU、內(nèi)存限制

• 重啟策略：restart: unless-stopped

• 環(huán)境變量：敏感信息通過 .env 文件管理

• 數(shù)據(jù)卷：

  • PostgreSQL 數(shù)據(jù)持久化

  • 日志目錄掛載

  • CubeJS 配置持久化

3.3 在線升級(jí)機(jī)制

升級(jí)流程設(shè)計(jì)：

1. 版本檢查
   ├─ 檢查當(dāng)前版本
   ├─ 檢查可用新版本
   └─ 檢查升級(jí)路徑兼容性
?
2. 備份階段
   ├─ 數(shù)據(jù)庫備份
   ├─ 配置文件備份
   └─ 當(dāng)前鏡像標(biāo)記保存
?
3. 升級(jí)執(zhí)行
   ├─ 拉取新版本鏡像
   ├─ 執(zhí)行數(shù)據(jù)庫遷移（如有）
   ├─ 更新配置文件
   ├─ 滾動(dòng)更新服務(wù)（零停機(jī)）
   └─ 驗(yàn)證服務(wù)健康
?
4. 回滾準(zhǔn)備
   └─ 如升級(jí)失敗，自動(dòng)/手動(dòng)回滾

升級(jí)方式選擇：

• 方案A：滾動(dòng)更新（推薦）

  • 使用 Docker Compose 的滾動(dòng)更新功能

  • 確保至少有一個(gè)實(shí)例始終運(yùn)行

  • 適合生產(chǎn)環(huán)境

• 方案B：藍(lán)綠部署

  • 部署新版本到獨(dú)立環(huán)境

  • 切換流量后停止舊版本

  • 適合大版本升級(jí)

• 方案C：基于版本標(biāo)簽切換

  • 使用 Docker Compose 環(huán)境變量指定版本

  • 通過更新 .env 文件切換版本

  • 簡單易用，適合小團(tuán)隊(duì)

四、關(guān)鍵技術(shù)實(shí)現(xiàn)點(diǎn)

4.1 版本管理

• 版本注入：

  • 構(gòu)建時(shí)通過 --build-arg 傳入版本號(hào)

  • 在代碼中暴露 /api/version 端點(diǎn)

  • 鏡像標(biāo)簽包含版本信息

• 版本查詢：

  # 在應(yīng)用中暴露版本信息
  @app.get("/api/version")
  async def get_version():
      return {
          "version": os.getenv("APP_VERSION", "unknown"),
          "build_time": os.getenv("BUILD_TIME", "unknown"),
          "git_commit": os.getenv("GIT_COMMIT", "unknown")
      }

4.2 健康檢查

• 應(yīng)用健康檢查：/health 端點(diǎn)（已有）

• 數(shù)據(jù)庫連接檢查

• 依賴服務(wù)檢查（CubeJS、Redis）

• Docker 健康檢查：在 Compose 中配置

4.3 數(shù)據(jù)遷移處理

• 數(shù)據(jù)庫遷移腳本：使用 Alembic 或自定義遷移腳本

• 遷移時(shí)機(jī)：升級(jí)前檢查并執(zhí)行必要的遷移

• 遷移回滾：保留回滾腳本

4.4 配置管理

• 環(huán)境變量模板：提供 .env.example

• 配置驗(yàn)證：啟動(dòng)前驗(yàn)證必需配置

• 配置熱更新：支持部分配置無需重啟的更新

五、客戶交付包設(shè)計(jì)

5.1 交付包內(nèi)容

aixx-delivery-v1.0.0/
├── README.md                    # 部署說明
├── QUICKSTART.md                # 快速啟動(dòng)指南
├── docker-compose.yml           # 生產(chǎn)環(huán)境編排
├── .env.example                 # 環(huán)境變量模板
├── docker/                      # 部署腳本目錄
│   ├── init.sh                 # 初始化腳本
│   ├── upgrade.sh              # 升級(jí)腳本
│   ├── backup.sh               # 備份腳本
│   └── healthcheck.sh          # 健康檢查腳本
├── scripts/                     # 工具腳本
│   ├── setup.sh                # 一鍵部署腳本
│   └── migrate.sh              # 數(shù)據(jù)遷移腳本
└── docs/                        # 文檔目錄
    ├── DEPLOYMENT.md            # 部署文檔
    ├── UPGRADE.md              # 升級(jí)文檔
    └── TROUBLESHOOTING.md      # 故障排查文檔

5.2 一鍵部署腳本功能

• 環(huán)境檢查（Docker、Docker Compose 版本）

• 配置文件生成和驗(yàn)證

• 數(shù)據(jù)目錄創(chuàng)建和權(quán)限設(shè)置

• 服務(wù)啟動(dòng)和驗(yàn)證

• 初始數(shù)據(jù)導(dǎo)入（可選）

六、升級(jí)腳本設(shè)計(jì)

6.1 升級(jí)腳本功能

./upgrade.sh [選項(xiàng)]
  --version VERSION      # 指定升級(jí)版本
  --check                # 僅檢查可用版本
  --rollback             # 回滾到上一版本
  --force                # 強(qiáng)制升級(jí)（跳過檢查）
  --dry-run              # 預(yù)覽模式，不實(shí)際執(zhí)行

6.2 升級(jí)腳本執(zhí)行流程

1. 前置檢查：環(huán)境、版本、兼容性

2. 備份：數(shù)據(jù)庫、配置、當(dāng)前鏡像

3. 下載：拉取新版本鏡像

4. 遷移：執(zhí)行數(shù)據(jù)庫遷移（如有）

5. 更新：滾動(dòng)更新容器

6. 驗(yàn)證：健康檢查和服務(wù)驗(yàn)證

7. 清理：清理舊鏡像（可選）

七、安全考慮

1. 鏡像安全：

   • 使用官方基礎(chǔ)鏡像

   • 定期更新依賴修復(fù)漏洞

   • 鏡像簽名驗(yàn)證（可選）

2. 數(shù)據(jù)安全：

   • 敏感數(shù)據(jù)加密存儲(chǔ)

   • 備份加密

   • 訪問權(quán)限控制

3. 網(wǎng)絡(luò)安全：

   • 最小端口暴露

   • 使用內(nèi)部網(wǎng)絡(luò)通信

   • TLS/SSL 加密（生產(chǎn)環(huán)境）

八、監(jiān)控與日志

1. 日志管理：

   • 統(tǒng)一日志格式

   • 日志輪轉(zhuǎn)策略

   • 日志收集（可選集成 ELK）

2. 監(jiān)控指標(biāo)：

   • 容器資源使用

   • 應(yīng)用性能指標(biāo)

   • 健康檢查狀態(tài)

九、實(shí)施步驟建議

第一階段：基礎(chǔ)容器化

1. 創(chuàng)建生產(chǎn)環(huán)境 Dockerfile

2. 創(chuàng)建生產(chǎn)環(huán)境 docker-compose.yml

3. 實(shí)現(xiàn)基本的啟動(dòng)和健康檢查

第二階段：版本管理

1. 實(shí)現(xiàn)版本注入機(jī)制

2. 添加版本查詢 API

3. 完善版本標(biāo)簽策略

第三階段：升級(jí)機(jī)制

1. 開發(fā)升級(jí)腳本

2. 實(shí)現(xiàn)備份機(jī)制

3. 測試升級(jí)流程

第四階段：交付優(yōu)化

1. 編寫部署文檔

2. 創(chuàng)建一鍵部署腳本

3. 完善錯(cuò)誤處理和日志

第五階段：測試驗(yàn)證

1. 在不同環(huán)境測試部署

2. 測試升級(jí)和回滾流程

3. 性能和安全測試

十、注意事項(xiàng)

1. 向后兼容：確保升級(jí)時(shí) API 和數(shù)據(jù)結(jié)構(gòu)向后兼容

2. 數(shù)據(jù)遷移：仔細(xì)設(shè)計(jì)數(shù)據(jù)庫遷移策略，確保數(shù)據(jù)安全

3. 零停機(jī)：使用滾動(dòng)更新確保服務(wù)連續(xù)性

4. 文檔完善：提供清晰的部署和升級(jí)文檔

5. 測試充分：在生產(chǎn)環(huán)境前充分測試所有流程

該方案便于：

• 標(biāo)準(zhǔn)化交付

• 簡單升級(jí)（一鍵或腳本化）

• 支持回滾

• 便于維護(hù)和管理

如需，我可以先實(shí)現(xiàn) Dockerfile 和生產(chǎn)環(huán)境的 docker-compose.yml 作為第一步。您希望先從哪部分開始？

 

 

V2

V2

針對(duì)客戶可能無公網(wǎng) IP 或受限訪問的情況，重新設(shè)計(jì)升級(jí)機(jī)制，采用客戶端主動(dòng)輪詢檢查新版本的方案。

以下是適用于客戶環(huán)境的“客戶端主動(dòng)輪詢檢查版本”升級(jí)方案：

客戶端主動(dòng)輪詢升級(jí)方案

一、架構(gòu)設(shè)計(jì)

1.1 升級(jí)流程

客戶端應(yīng)用（定時(shí)任務(wù)）
    ↓
定期訪問您的版本檢查服務(wù)器
    ↓
獲取最新版本信息
    ↓
與本地版本對(duì)比
    ↓
如有新版本 → 提示用戶
    ↓
用戶選擇升級(jí)
    ↓
下載新版本文件或拉取鏡像
    ↓
執(zhí)行升級(jí)腳本

1.2 關(guān)鍵組件

服務(wù)器端（您這邊）：

1. 版本檢查 API：提供版本信息的 HTTP 接口

2. 版本發(fā)布服務(wù)：管理版本信息和下載鏈接

3. 鏡像倉庫：存儲(chǔ) Docker 鏡像（可選，如果客戶能訪問）

客戶端（客戶環(huán)境）：

1. 版本檢查定時(shí)任務(wù)：定期檢查新版本

2. 版本信息 API：返回當(dāng)前運(yùn)行版本

3. 升級(jí)提示界面：前端顯示更新提示

4. 升級(jí)腳本：支持手動(dòng)和自動(dòng)升級(jí)

二、版本檢查服務(wù)器 API 設(shè)計(jì)

2.1 API 接口設(shè)計(jì)

版本檢查端點(diǎn)（您的服務(wù)器）：

GET https://your-update-server.com/api/v1/version/check
參數(shù)：
  - current_version: 客戶端當(dāng)前版本（可選）
  - product: chatbi（產(chǎn)品標(biāo)識(shí)）
?
返回：
{
  "has_update": true,
  "latest_version": "1.0.1",
  "current_version": "1.0.0",
  "release_notes": "修復(fù)了一些bug，新增了XXX功能",
  "release_date": "2025-01-15",
  "update_type": "minor",  // major/minor/patch
  "download_urls": {
    "docker_image": "registry.example.com/chatbi:1.0.1",
    "tar_package": "https://example.com/downloads/chatbi-1.0.1.tar.gz",
    "checksum": "https://example.com/downloads/chatbi-1.0.1.sha256"
  },
  "changelog": "詳細(xì)的更新日志",
  "required": false,  // 是否強(qiáng)制升級(jí)
  "compatibility": {
    "min_current_version": "1.0.0"  // 支持從哪個(gè)版本升級(jí)
  }
}

2.2 版本信息管理

版本數(shù)據(jù)庫結(jié)構(gòu)（建議）：

CREATE TABLE versions (
  id SERIAL PRIMARY KEY,
  version VARCHAR(50) UNIQUE NOT NULL,
  release_date TIMESTAMP NOT NULL,
  update_type VARCHAR(20),  -- major/minor/patch
  release_notes TEXT,
  changelog TEXT,
  download_url_docker TEXT,
  download_url_tar TEXT,
  checksum_sha256 VARCHAR(64),
  required BOOLEAN DEFAULT FALSE,
  min_upgrade_version VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW()
);

三、客戶端版本檢查實(shí)現(xiàn)

3.1 客戶端版本檢查定時(shí)任務(wù)

實(shí)現(xiàn)方式選擇：

方案A：應(yīng)用內(nèi)后臺(tái)任務(wù)（推薦）

• 在 FastAPI 啟動(dòng)時(shí)啟動(dòng)后臺(tái)任務(wù)

• 定期訪問版本檢查 API

• 將版本信息存儲(chǔ)到數(shù)據(jù)庫或緩存

• 前端通過 API 獲取更新提示

方案B：獨(dú)立的升級(jí)檢查服務(wù)

• 單獨(dú)的輕量級(jí)容器定期檢查

• 將結(jié)果寫入共享存儲(chǔ)或數(shù)據(jù)庫

• 主應(yīng)用讀取版本信息

方案C：Systemd Timer / Cron（Linux）或計(jì)劃任務(wù)（Windows）

• 在主機(jī)上配置定時(shí)任務(wù)

• 調(diào)用檢查腳本

• 將結(jié)果寫入文件或數(shù)據(jù)庫

3.2 客戶端版本檢查代碼設(shè)計(jì)

版本檢查模塊設(shè)計(jì)：

# chatbi/services/version_check.py
- check_update_available()  # 檢查是否有更新
- get_current_version()     # 獲取當(dāng)前版本
- store_update_info()       # 存儲(chǔ)更新信息
- schedule_version_check()  # 定時(shí)任務(wù)

后臺(tái)定時(shí)任務(wù)：

# 在應(yīng)用啟動(dòng)時(shí)啟動(dòng)
- 每 24 小時(shí)檢查一次（可配置）
- 失敗時(shí)重試機(jī)制
- 檢查結(jié)果緩存
- 記錄檢查日志

四、升級(jí)方式設(shè)計(jì)

4.1 升級(jí)方式選擇

方式1：手動(dòng)下載升級(jí)（適合無公網(wǎng)IP環(huán)境）

1. 用戶在前端看到更新提示
2. 點(diǎn)擊下載按鈕，下載新版本包
3. 上傳到服務(wù)器
4. 執(zhí)行升級(jí)腳本

方式2：自動(dòng)拉取鏡像（適合能訪問互聯(lián)網(wǎng)的環(huán)境）

1. 用戶確認(rèn)升級(jí)
2. 自動(dòng)從鏡像倉庫拉取新版本
3. 執(zhí)行升級(jí)腳本

方式3：離線升級(jí)包（最通用）

1. 提供完整的離線升級(jí)包（包含鏡像文件）
2. 用戶下載后，通過腳本導(dǎo)入鏡像
3. 執(zhí)行升級(jí)

4.2 升級(jí)包結(jié)構(gòu)

離線升級(jí)包內(nèi)容：

aixx-upgrade-v1.0.1/
├── README.md                    # 升級(jí)說明
├── CHANGELOG.md                 # 更新日志
├── upgrade.sh                   # 升級(jí)腳本
├── rollback.sh                  # 回滾腳本
├── docker-compose.yml           # 新版本編排文件
├── images/                      # Docker 鏡像文件
│   ├── aixx-app-v1.0.1.tar   # 應(yīng)用鏡像
│   └── ...                      # 其他依賴鏡像（如有更新）
├── migrations/                  # 數(shù)據(jù)庫遷移腳本（如有）
│   └── v1.0.0_to_v1.0.1.sql
└── checksums.sha256             # 校驗(yàn)文件

五、客戶端實(shí)現(xiàn)細(xì)節(jié)

5.1 版本信息存儲(chǔ)

數(shù)據(jù)庫表設(shè)計(jì)：

# 版本信息表
class UpdateInfo(Base):
    __tablename__ = "update_info"
    
    id = Column(Integer, primary_key=True)
    latest_version = Column(String(50))      # 最新版本
    current_version = Column(String(50))      # 當(dāng)前版本
    has_update = Column(Boolean, default=False)
    check_time = Column(DateTime)             # 檢查時(shí)間
    update_info = Column(JSON)                 # 完整更新信息
    notified = Column(Boolean, default=False)   # 是否已通知用戶

5.2 前端更新提示

API 端點(diǎn)（客戶端應(yīng)用提供）：

GET /api/v1/update/check        # 手動(dòng)觸發(fā)檢查
GET /api/v1/update/info         # 獲取更新信息
POST /api/v1/update/download    # 觸發(fā)下載（如果支持）

前端顯示：

• 系統(tǒng)設(shè)置頁面顯示當(dāng)前版本和最新版本

• 如有更新，顯示更新提示橫幅

• 更新詳情彈窗（版本號(hào)、更新日志、下載鏈接）

六、升級(jí)腳本增強(qiáng)

6.1 升級(jí)腳本功能擴(kuò)展

支持多種升級(jí)方式：

./upgrade.sh [選項(xiàng)]
  --version VERSION        # 指定版本
  --from-file FILE         # 從離線包升級(jí)
  --from-url URL           # 從下載鏈接升級(jí)
  --from-registry          # 從鏡像倉庫拉取
  --check-only             # 僅檢查
  --force                  # 強(qiáng)制升級(jí)

升級(jí)流程：

1. 檢查當(dāng)前版本和環(huán)境
2. 根據(jù)升級(jí)方式獲取新版本文件
   ├─ 離線包：解壓并加載鏡像
   ├─ 下載鏈接：下載并驗(yàn)證
   └─ 鏡像倉庫：拉取鏡像
3. 驗(yàn)證文件完整性（校驗(yàn)和）
4. 備份數(shù)據(jù)和配置
5. 執(zhí)行數(shù)據(jù)庫遷移（如有）
6. 更新容器
7. 健康檢查
8. 如失敗，自動(dòng)回滾

七、實(shí)施計(jì)劃

7.1 第一階段：版本檢查功能

服務(wù)器端：

1. 創(chuàng)建版本檢查 API（您的服務(wù)器）

2. 版本信息管理后臺(tái)

3. 下載鏈接管理

客戶端：

1. 版本信息暴露 API（獲取當(dāng)前版本）

2. 版本檢查定時(shí)任務(wù)

3. 更新信息存儲(chǔ)（數(shù)據(jù)庫）

4. 前端更新提示界面

7.2 第二階段：升級(jí)功能

1. 升級(jí)腳本增強(qiáng)（支持多種方式）

2. 離線升級(jí)包生成腳本

3. 升級(jí)向?qū)Ы缑妫ㄇ岸耍?/span>

4. 升級(jí)日志和回滾機(jī)制

7.3 第三階段：優(yōu)化

1. 升級(jí)進(jìn)度顯示

2. 自動(dòng)重試機(jī)制

3. 升級(jí)統(tǒng)計(jì)（匿名）

4. 升級(jí)通知優(yōu)化

八、配置項(xiàng)設(shè)計(jì)

8.1 客戶端配置

環(huán)境變量或配置文件：

# 版本檢查配置
VERSION_CHECK_ENABLED=true           # 是否啟用版本檢查
VERSION_CHECK_INTERVAL=86400         # 檢查間隔（秒，默認(rèn)24小時(shí)）
VERSION_CHECK_SERVER=https://your-update-server.com  # 版本檢查服務(wù)器
VERSION_CHECK_TIMEOUT=10             # 請(qǐng)求超時(shí)（秒）
VERSION_CHECK_RETRY=3                # 失敗重試次數(shù)
?
# 升級(jí)配置
UPGRADE_DOWNLOAD_DIR=/data/upgrades  # 升級(jí)包存儲(chǔ)目錄
UPGRADE_AUTO_ENABLED=false           # 是否自動(dòng)升級(jí)（建議關(guān)閉）

8.2 服務(wù)器端配置

版本發(fā)布配置：

• 版本號(hào)管理規(guī)則（語義化版本）

• 下載鏈接生成

• 鏡像倉庫配置

• CDN 配置（如果使用）

九、安全考慮

1. 版本檢查 API

   • HTTPS

   • API 密鑰驗(yàn)證（可選）

   • 限流

2. 升級(jí)文件驗(yàn)證

   • SHA256 校驗(yàn)

   • GPG 簽名（可選）

   • 文件完整性檢查

3. 升級(jí)過程安全

   • 備份驗(yàn)證

   • 回滾機(jī)制

   • 操作日志

十、用戶體驗(yàn)設(shè)計(jì)

1. 更新提示

   • 非強(qiáng)制更新：優(yōu)雅提示，不打斷用戶

   • 強(qiáng)制更新：明確提示并引導(dǎo)升級(jí)

2. 升級(jí)過程

   • 進(jìn)度顯示

   • 狀態(tài)反饋

   • 錯(cuò)誤提示

3. 升級(jí)后

   • 版本信息確認(rèn)

   • 新功能引導(dǎo)（可選）

方案優(yōu)勢(shì)

1. 無需公網(wǎng) IP：客戶端主動(dòng)訪問，單向通信即可

2. 靈活升級(jí)：支持離線包、下載、鏡像拉取

3. 用戶體驗(yàn)：定時(shí)檢查，及時(shí)提示

4. 安全可控：文件校驗(yàn)、回滾、操作日志

5. 兼容性好：適配不同網(wǎng)絡(luò)環(huán)境

如需，我可以先實(shí)現(xiàn)客戶端版本檢查定時(shí)任務(wù)和版本信息 API，作為第一步。需要我開始嗎？