Dcard Data Monorepo 指南

總覽

一句話：UV workspace + just + 客製 affected detection + CircleCI dynamic config。

目錄結構

dcard-data/
├── pyproject.toml          # UV workspace root
├── uv.lock                 # 統一 lock file
├── justfile                # 入口任務
│
├── libs/                   # 共用 Python packages
│   ├── dcard-api/          # FastAPI scaffolding (app/metrics/health)
│   ├── dcard-bigtable/     # Bigtable client utilities
│   ├── dcard-mongo/        # MongoDB client utilities
│   ├── dcard-observability/ # Prometheus metrics utilities
│   └── dcard-redis/        # Redis/RediSearch client utilities
│
├── services/               # 獨立部署的 services
│   ├── ad-cdc-sync/        # CDC 同步廣告素材到 RediSearch (consumer)
│   ├── ad-product-ranking/ # 動態商品排序 (api)
│   ├── feast-grpc/         # Feast gRPC feature store server (api/gRPC)
│   ├── youji-api/          # DAD 平台 API (api)
│   └── youji-audience-sketch/ # 受眾估算 Spark job (spark)
│
├── scripts/                # Build 和 CI 工具
│   ├── init-api-service.sh # 建立新 API service
│   └── affected.py         # Git diff 偵測受影響的 packages
│
└── .circleci/config.yml    # setup workflow，跳轉到 dynamic config

重要檔案

環境設定

# 裝 UV
curl -LsSf https://astral.sh/uv/install.sh | sh      # or: brew install uv

# 裝 just
brew install just

# Clone
git clone git@github.com:Dcard/Dcard-Data.git
cd dcard-data

# 裝所有 workspace deps（一次裝好、所有 service / lib 共用一個 venv）
uv sync --all-packages

# 或只裝特定 service 的 scope
uv sync --dev --package youji-api

just 指令

just --list 列出所有可用指令。最常用的：

Services

每個 service 結構一致：

services/<name>/
├── pyproject.toml          # workspace member
├── Dockerfile              # multi-stage, uv pinned 0.5
├── service.yml             # 部署 metadata（type / image / 資源名 / 健檢）
├── src/<package_name>/     # 大多 service 用 src layout
└── tests/

Libs

只有在「多個 service 要共用的程式碼」才抽成 lib。用 workspace dep 引入：

# services/my-service/pyproject.toml
dependencies = [
    "dcard-api",
    "dcard-mongo",
]

[tool.uv.sources]
dcard-api = { workspace = true }
dcard-mongo = { workspace = true }

新增 API service

just init-api-service my-new-service

會在 services/my-new-service/ 產出：

• pyproject.toml — 已 workspace + dcard-api dep
• Dockerfile — multi-stage、uv 0.5 pinned、非 root user、BuildKit cache mount、PYTHONDONTWRITEBYTECODE / PYTHONUNBUFFERED
• service.yml — type: api、扁平 deploy.image + deploy.resource_name
• docker-entrypoint.sh — exec gunicorn ...（PID 1 讓 SIGTERM 直接到 gunicorn，graceful shutdown）
• src/my_new_service/main.py — 用 dcard_api.create_app() 起 FastAPI
• tests/test_health.py — 最基本的 /healthz 測試

Affected 偵測

scripts/affected.py 是整個 CI 動態行為的核心。它分析 git diff，告訴你哪些 packages（services + libs）受影響。

變更位置                              受影響
─────────────────────────────────── ──────────────────────────
services/<X>/...                     service X
libs/<Y>/...                         lib Y + transitive 依賴 Y 的所有 libs + services
pyproject.toml / .python-version     所有 services + libs

Lib 之間有 dependency（例如 dcard-api → dcard-observability），偵測會做傳遞閉包：改 dcard-observability 會拉出 dcard-api、dcard-mongo、dcard-redis、dcard-bigtable 等 lib，加上這些 lib 下游所有 services。

# 手動試偵測
just affected

# 看會產生什麼 CircleCI YAML
just ci-config

Pipeline 流程

每個受影響的 service 都會走完整的 build → deploy → approve → deploy prod：

test-<service>  →  build-<service>  →  deploy-staging-<service>
                                           ↓
                                   approve-production-<service> (manual hold)
                                           ↓
                                   deploy-production-<service>

test-lib-<lib>   （libs 有自己獨立 test job，跟 services 並行）

Docker image 一次打兩個 tag：:latest + :<git-sha>。Production rollback 時用 SHA 可以精準回到特定 commit：

kubectl --context=<prod-cluster> \
  set image deployment/<name> \
  <container>=asia-east1-docker.pkg.dev/dcard-data/modules/<image>:<old-sha>

service.yml

這是 service 向 CI 自我介紹的檔案。affected.py 讀它來決定要產什麼 build / deploy job。

# 最常見：HTTP API
name: my-service
team: ad-recommendation
type: api

deploy:
  image: dcard-my-service             # 在 Artifact Registry 的 image 名
  resource_name: dcard-my-service     # k8s deployment 名字（=container name）

# Consumer（一個 image 多個 k8s deployment — 拆不同訊息 stream）
type: consumer
deploy:
  image: dcard-ad-cdc-sync
  resource_names:
    - dcard-youji-ad-cdc-sync-adset
    - dcard-youji-ad-cdc-sync-candidate
    - dcard-youji-ad-cdc-sync-reserve-bid-price

# gRPC 或非預設 port + 健檢設定
type: api

deploy:
  image: dcard-feast-grpc
  resource_name: dcard-feast-grpc
  container_port: 50051                 # 非 8000 的主要服務 port
  healthcheck:
    port: 2112                          # 健檢 port 跟服務 port 不同時填
    path: /health

# Spark job
type: spark
deploy:
  gcs_bucket_staging: dcard-ad-targeting-staging-asia
  gcs_bucket_production: dcard-ad-targeting-asia
  gcs_prefix: dataproc/my_job
  artifacts:
    - { type: file, src: src/main.py }
    - { type: zip,  src: src/utils/, name: utils.zip }

Docker 慣例

所有 service 的 Dockerfile 都遵循一套 pattern（由 init script 產、手動維護）：

• Build from repo root — 因為要能讀到 workspace 的 pyproject.toml + uv.lock。docker build -f services/<name>/Dockerfile .（路徑給 -f，context 給 .）。
• Pinned uv 版本 — COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /bin/uv，不用 :latest。
• BuildKit cache mount — RUN --mount=type=cache,target=/root/.cache/uv uv sync ...，CI 多次 build 時 cache 命中。
• Non-root user — useradd -m -u 1000 app、USER app。
• Exec gunicorn — entrypoint.sh 用 exec gunicorn ... 讓 gunicorn 當 PID 1，k8s SIGTERM graceful shutdown 才有效。
• Python env vars — PYTHONDONTWRITEBYTECODE=1、PYTHONUNBUFFERED=1。
• 只 COPY 需要的 libs — 不是整個 libs/ 都塞進 image，只複製該 service 有用到的。

Bigtable warmup

用到 dcard-bigtable 的 service，第一個請求會踩 Bigtable gRPC channel 冷啟動 — channel 建立 + auth token + routing metadata 動輒上百毫秒，超過 lib default 的 150ms timeout 就會回 500。

解法：在 FastAPI lifespan 裡加一行 warmup：

from dcard_bigtable import AsyncBigtableClientBase

bigtable = AsyncBigtableClientBase(project=...)

@asynccontextmanager
async def lifespan(app):
    # ... other init ...
    await bigtable.warmup("feature-store", bigtable_table_id)
    yield

warmup() 會 issue 一個 read_rows(limit=1)，用寬鬆的 5s timeout 把 channel + auth 全部預熱一次。失敗會 log warning 但不 block startup。

疑難排解

uv sync 失敗

rm -rf .venv
uv sync --all-packages

改 lib 了，CI 卻沒跑我想跑的 service 測試

檢查 services/<name>/pyproject.toml 是否明確宣告 workspace dep：

dependencies = ["dcard-mongo"]
[tool.uv.sources]
dcard-mongo = { workspace = true }

沒宣告的話 affected detector 看不到關聯。

CI 上 build 成功但 pod crash

多半是 non-root user 權限問題或 env 缺失。先 docker run --entrypoint sh <image> -c 'id && env' 看 user 是 1000 + 該有的 env 都在；再用 kubectl logs 看 pod startup log。

Production deploy 要手動 approve

這是設計。Staging auto-deploy；Production 卡在 approve-production-<service> 這個 hold job，透過 CircleCI UI 或 POST /api/v2/workflow/<wid>/approve/<job-id> 放行。放行後自動 rolling update。

Dependabot 告警

根 pyproject.toml 或某個 service 的 pyproject 裡升級版本後，uv lock 重產。lock 變動會自動觸發 affected detector 把全部 services 都拉進來跑一輪測試。