Rails migration 可以寫成：

class AddEmailToUsers < ActiveRecord::Migration[7.1]
  def change
    add_column :users, :email, :string
  end
end

或明確分開：

class AddEmailToUsers < ActiveRecord::Migration[7.1]
  def up
    add_column :users, :email, :string
  end

  def down
    remove_column :users, :email
  end
end

change 比較短，Rails 會自動推導出 rollback (db:rollback 時執行反向操作)。看起來 change 永遠好，但不是。

change 可以幫你推導的指令

官方清單 (API docs)：

• create_table ↔ drop_table
• add_column ↔ remove_column
• add_index ↔ remove_index
• add_reference ↔ remove_reference
• add_foreign_key ↔ remove_foreign_key
• change_column_default (帶 from: / to:)
• change_column_null
• rename_column, rename_index, rename_table

這些 Rails 知道怎麼反過來。只用這些的 migration 可以放心用 change。

什麼時候一定要寫 up/down

1. change_column 改型態

def change
  change_column :users, :age, :integer   # ← 原本是什麼？
end

Rails 不知道「原本是什麼型態」，rollback 時不知道要改回啥。必須：

def up
  change_column :users, :age, :integer
end

def down
  change_column :users, :age, :string
end

2. 有 data migration (寫資料)

def change
  add_column :users, :full_name, :string
  User.reset_column_information
  User.find_each { |u| u.update!(full_name: "#{u.first_name} #{u.last_name}") }
end

rollback 時怎麼還原？沒辦法。而且這整段 data migration 放 migration 裡本身就有問題 (下面再講)，但如果真的要做，至少要明確 up / down：

def up
  add_column :users, :full_name, :string
  # data migration
end

def down
  remove_column :users, :full_name
end

3. execute 直接跑 SQL

def change
  execute "UPDATE users SET role = 'member' WHERE role IS NULL"
end

跟上面同理，Rails 不會去 parse SQL 然後反推。必須分成 up / down，或用 reversible：

def change
  reversible do |dir|
    dir.up   { execute "UPDATE users SET role = 'member' WHERE role IS NULL" }
    dir.down { execute "UPDATE users SET role = NULL WHERE role = 'member'" }
  end
end

4. 真的不可逆

def up
  remove_column :users, :legacy_token  # 資料就這樣消失
end

def down
  raise ActiveRecord::IrreversibleMigration
end

誠實寫出來，不要騙自己可以回。也可以在 change 裡用 Rails 提供的 block：

def change
  remove_column :users, :legacy_token, :string   # ← 注意：要指定原本的型態
end

remove_column 帶型態時 Rails 可以從 drop_column 推回 add_column，反向可逆。

我自己的 rule of thumb

• 純 schema change、且在「Rails 知道怎麼 reverse 的清單」裡 → 用 change。
• 含 data migration → 不應該跟 schema change 綁在同一個 migration，拆兩支。schema 那支用 change，data 那支用另一種機制 (下面講)。
• 含 execute SQL / change_column 改型 → 寫 up / down，或用 reversible。
• 真的不可逆 → 寫 up，在 down 明確 raise IrreversibleMigration。

不確定時優先寫 up/down。多打幾行總比半夜 rollback 時 migration 自己說「我不知道怎麼回去」好。

Data migration 不要放 schema migration 裡

即使你寫得漂漂亮亮的 reversible，實務上 schema migration 裡跑資料更新 還是有兩個麻煩：

1. 大 table 會 timeout

User.find_each { |u| u.update!(full_name: "#{u.first_name} #{u.last_name}") }

1000 萬筆 user，這段跑幾小時。migration 鎖表、deploy 掛在那、DBA 電話進來。

2. Model code 跟 schema 版本錯開

migration 寫在 20260424120000_backfill_full_name.rb 時用 User model，半年後 User 已經加了新欄位、新 callback、新 validation。這支 migration 在 rollback 或 schema re-setup 時又被跑一次，可能 behavior 完全不一樣。

比較好的 pattern：schema migration 只改 schema，data backfill 跑 rake task 或獨立的 maintenance job：

# lib/tasks/backfill_full_name.rake
namespace :backfill do
  task full_name: :environment do
    User.where(full_name: nil).find_each(batch_size: 1000) do |u|
      u.update_columns(full_name: "#{u.first_name} #{u.last_name}")
    end
  end
end

Deploy flow：

1. Deploy 帶 schema migration 的 commit → add_column :users, :full_name。
2. rails backfill:full_name 跑一次 (可中斷、可 monitor、可分批)。
3. Deploy 移除舊欄位 / 加 NOT NULL constraint 的 commit。

雖然步驟變多，但每一步都小、可回退、可 monitor。

小結

• change 給純 schema 用。
• change_column 型態改變 / execute SQL / data migration → 寫 up/down 或用 reversible。
• 真的不可逆就誠實 raise IrreversibleMigration。
• Schema migration 跟 data migration 分開。schema 用 change，data 用 rake task。

前端多語系站通常是這樣做 lazy loading 的：

async function loadLocale(locale) {
  const res = await fetch(`/locales/${locale}.json`);
  if (!res.ok) throw new Error('load failed');
  return res.json();
}

export async function initI18n(locale = 'zh-TW') {
  try {
    const messages = await loadLocale(locale);
    i18n.setMessages(messages);
  } catch (e) {
    // fallback
    const messages = await loadLocale('en');
    i18n.setMessages(messages);
  }
}

看起來 reasonable — 抓不到就用英文。直到有一天客人反應：「我用 Chrome 開你們的網站，第一次進站明明 UI 語言是中文，但突然就跳英文了」。

為什麼會這樣

幾個常見觸發點：

1. 第一次進站網路很爛：手機從 4G 轉 WiFi、地下室訊號差、CDN 抖一下。fetch timeout / 連線斷線 → catch 觸發 → 掉到 en。
2. CDN cache miss + 後端短暫 500：/locales/zh-TW.json 第一次真的回 500，之後就正常了。但那位 user 第一次的體驗就是 en。
3. service worker 還在 install：第一次 request 沒被 cache，service worker 繞路的過程中 race，fetch 失敗。

後果都一樣：user 其實是中文使用者，但被強制看到英文。糟糕的 UX — 英文使用者反而不會受影響。

解法：fallback 要看瀏覽器語言再決定

function pickFallbackLocale(supported) {
  const pref = navigator.languages || [navigator.language];
  for (const tag of pref) {
    // 先試完整 match
    if (supported.includes(tag)) return tag;
    // 再試 primary subtag (zh-TW → zh)
    const primary = tag.split('-')[0];
    const hit = supported.find(s => s.startsWith(primary + '-') || s === primary);
    if (hit) return hit;
  }
  return 'en'; // 真的都沒 match 才英文
}

const SUPPORTED = ['zh-TW', 'zh-CN', 'ja', 'en'];

export async function initI18n(locale) {
  const target = locale || pickFallbackLocale(SUPPORTED);
  try {
    i18n.setMessages(await loadLocale(target));
  } catch (e) {
    const fallback = pickFallbackLocale(SUPPORTED.filter(s => s !== target));
    i18n.setMessages(await loadLocale(fallback));
  }
}

要點

1. navigator.languages 優先於 navigator.language。前者是 array，按使用者設定的優先順序排。後者只有一個。
2. Primary subtag match。user browser 是 zh-HK，站只支援 zh-TW / zh-CN — 這時候 zh-TW (或 zh-CN，依你覺得誰離 HK 近) 比 en 合理太多。
3. fallback 的 fallback 也不要是 en。[ja] 掛掉時，user 是日文，退到 zh-TW 都比 en 合理一點 — 但這個 case 太邊界，多數情況下真的都掛掉就給 en 即可。
4. BCP 47 case：zh-tw / zh-TW / ZH-TW 要統一 normalize。瀏覽器通常回 zh-TW，但要防呆。

如果你用 i18next / vue-i18n

一樣的邏輯已經有現成選項：

// i18next
i18next.init({
  fallbackLng: {
    'zh-HK': ['zh-TW', 'zh-CN', 'en'],
    'zh-MO': ['zh-TW', 'zh-CN', 'en'],
    default: ['en'],
  },
  detection: {
    order: ['querystring', 'cookie', 'navigator'],
  },
});

重點不是哪個 lib，而是 「載入失敗」跟「語言沒支援」的 fallback 路徑要分開想。大部分 lib 預設只處理「沒支援」的 fallback，載入失敗那條路是你自己要補的。

還要記得：user override 要 persist

第一次靠 navigator 猜語言沒關係，但 user 手動切換語言之後，要記住。

function getPreferredLocale() {
  return (
    localStorage.getItem('locale') ||           // 手動選過的
    pickFallbackLocale(SUPPORTED)               // 沒選過就猜
  );
}

function setPreferredLocale(locale) {
  localStorage.setItem('locale', locale);
  initI18n(locale);
}

不然就會變成「user 選了繁中、關掉視窗再進來，又變回簡中」— 一樣糟。

SSR 的版本

SSR 的情境下沒有 navigator，要從 request header 看：

// Next.js / Remix / Express
function pickFromAcceptLanguage(header, supported) {
  if (!header) return 'en';
  const candidates = header
    .split(',')
    .map(part => {
      const [tag, q = 'q=1'] = part.trim().split(';');
      return { tag: tag.trim(), q: parseFloat(q.split('=')[1]) };
    })
    .sort((a, b) => b.q - a.q);

  for (const { tag } of candidates) {
    if (supported.includes(tag)) return tag;
    const primary = tag.split('-')[0];
    const hit = supported.find(s => s.startsWith(primary));
    if (hit) return hit;
  }
  return 'en';
}

邏輯是一樣的，只是資料來源從 navigator.languages 換成 Accept-Language header。

小結

• 載入 locale JSON 失敗 → 直接 fallback en 是常見 UX bug。
• 用 navigator.languages + primary subtag match 決定 fallback，英文只是最後的保底。
• user 手動切換過的語言要 persist (localStorage / cookie)。
• SSR 情境讀 Accept-Language header，邏輯相同。

預設 docker run 跑出來的 process UID 是 0 (root)。這帶來幾個問題：

1. Container escape 風險：雖然有 namespace 隔離，但萬一 runtime (containerd / runc) 有洞，root in container 比 non-root 造成的傷害大得多。
2. 掛載宿主目錄時檔案權限變 root:root：宿主系統使用者之後要去清就要 sudo。
3. 某些 managed 平台 (OpenShift、GKE Autopilot、某些 PaaS) 根本不給 root 跑，container 啟動直接失敗。
4. 合規：SOC 2、ISO 27001、PCI-DSS audit 常見要求就是「container 不可以用 root」。

所以正確 pattern 是：

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

# 建立 non-root user
RUN useradd --create-home --shell /bin/bash appuser
USER appuser

CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

但會踩到下一個坑。

典型錯誤：log 目錄寫不進去

啟動 container：

PermissionError: [Errno 13] Permission denied: '/app/logs/app.log'

或用 Python logging RotatingFileHandler 的話：

FileNotFoundError: [Errno 2] No such file or directory: '/app/logs'

原因是：

1. COPY . . 時那些檔案的 owner 是 root (build stage 跑到 USER appuser 之前所有東西都還是 root-owned)。
2. Application 要寫的 /app/logs 不存在、或存在但是 root owner、appuser 無權寫入。

正確 Dockerfile 寫法

FROM python:3.12-slim

# 先建 user (固定 UID 方便 volume 權限管理)
RUN groupadd -g 1000 appuser && \
    useradd -u 1000 -g 1000 -m appuser

WORKDIR /app

# 把 WORKDIR 跟之後會 COPY 進來的東西 ownership 交給 appuser
COPY --chown=appuser:appuser requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser . .

# 建 runtime 會寫入的目錄，先開好權限
RUN mkdir -p /app/logs && chown -R appuser:appuser /app/logs

USER appuser

CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

幾個要點

1. --chown= 在 COPY 指令上。比 COPY . . && RUN chown -R appuser /app 好很多：第二種寫法會多一層 image，而且某些檔案大時 chown 本身就幾十 MB 的 layer。
2. runtime 會寫入的目錄 build time 就先建好。log、cache、tmp、upload buffer…… 全部提前 mkdir -p && chown。
3. 固定 UID/GID。如果會用 volumes: 掛宿主目錄，固定 UID 方便你在宿主上管權限：chown -R 1000:1000 /host/logs。
4. WORKDIR 的 owner 一般不用特別處理，但只要 app 要在 WORKDIR 直接寫檔 (log、sqlite dev db、webpack manifest 之類)，也要 chown。

把 log 改導到 stdout 才是更好的答案

上面的解法是讓 appuser 可以寫檔。但 containerized service 的最佳實踐是：log 全部寫到 stdout / stderr，讓 container runtime 負責收集。

# Python
import logging, sys
logging.basicConfig(
    stream=sys.stdout,
    level=logging.INFO,
    format='%(asctime)s %(levelname)s %(name)s %(message)s',
)

# Rails config/environments/production.rb
config.logger = ActiveSupport::Logger.new(STDOUT)
config.log_formatter = ::Logger::Formatter.new

這樣：

• 不用管目錄權限。
• k8s / ECS / Cloud Run 內建 log aggregation 直接收得到。
• Container 重啟時 log 不會丟 (跟容器內的 file log 不一樣)。
• 12-Factor app 第 11 條講的就是這個。

只有要做 local debug、或應用本身要產生 audit file (ex: ECPay 付款 log 需要留檔對帳) 才會真的寫到 file。那時候前面那段 Dockerfile 的 chown 處理就派上用場。

常見變形：alpine / distroless

Alpine base image (python:3.12-alpine、node:20-alpine) 的 useradd 不存在，要用 adduser：

RUN addgroup -g 1000 appuser && \
    adduser -u 1000 -G appuser -D appuser

Distroless base image (gcr.io/distroless/python3) 裡根本沒有 shell，也沒辦法 useradd。Distroless 已經內建 nonroot user (UID 65532)：

FROM gcr.io/distroless/python3
COPY --from=builder --chown=65532:65532 /app /app
USER 65532
CMD ["app.py"]

小結

• Container 預設 root，要主動切到 non-root user。
• Build time 就要把 runtime 會讀寫的檔案/目錄都 --chown 給那個 user。
• Log 寫 stdout，不要寫 file — 大部分情況下連權限問題都不會有。
• Alpine / distroless 的 user 建法不一樣，抄前先確認 base image。

很多 Dockerfile / docker-compose / k8s manifest 一開始會這樣寫：

# Python / FastAPI
CMD ["sh", "-c", "alembic upgrade head && uvicorn app:app --host 0.0.0.0"]

# Rails
CMD ["sh", "-c", "bundle exec rails db:migrate && bundle exec rails server"]

每個 container 啟動時先跑 migration 再起 service。單 replica 時看起來很合理、很方便，但只要 replica > 1 或有 rolling deploy，就會踩雷。

踩雷點 1：多 replica 同時 migrate

replicas: 3 的時候，k8s / ECS / Cloud Run 會同時啟三個 container。三個都跑：

alembic upgrade head

誰先拿到 migration 鎖 (alembic / Rails 都是用 CREATE TABLE alembic_version / schema_migrations) 誰就 run，其他兩個的狀況：

• Alembic：預設沒鎖 — 三個同時跑 ALTER TABLE 極大概率撞死 (MySQL metadata lock 互卡，或 DDL 直接衝突)。
• Rails：有 advisory lock，但等鎖時間可能超過 container health check timeout — 被 k8s 當作啟動失敗殺掉重啟，下一輪再重新搶 — 死循環 crashloop。

即使勉強跑過，log 會長得像：

alembic.util.exc.CommandError: Can't locate revision identified by 'abc123'

因為 replica A 把 revision 推到 abc123，replica B/C 的 container 啟動當下讀到的 metadata 已經不是它以為的狀態，alembic 就糊掉。

踩雷點 2：rollback 時 schema 比 code 新

Deploy v2 (帶 migration)：

t=0  replica A:  migrate → schema v2 ✅ + 跑 v2 code ✅
t=1  replica B:  啟動 → alembic upgrade head (已經 head 了 noop) → 跑 v2 code ✅
t=2  發現 v2 有 bug，rollback 回 v1
t=3  replica A/B/C 全部回到 v1 code，但 DB schema 還在 v2

v1 code 對 v2 schema 能不能跑，不保證。新增欄位通常安全、DROP COLUMN 幾乎必死、NOT NULL 新欄位會炸。Migration 跟 service start 綁在一起，代表沒有一個明確的時間點可以 decouple schema 版本跟 code 版本，rollback 選擇就變得超難。

踩雷點 3：Health check 起不來

CMD ["sh", "-c", "alembic upgrade head && uvicorn ..."]

大 migration 跑 10 分鐘。k8s readiness probe 預設 10 秒沒 ready 就重啟。結果是 container 重複啟動、重複嘗試跑 migration、從頭再來。Migration 永遠跑不完、service 永遠起不來。

正解：migration 當成 one-off job

Pattern A：CI/CD 裡單獨跑一步

# .github/workflows/deploy.yml
- name: Run DB migrations
  run: |
    docker run --rm \
      -e DATABASE_URL=$DATABASE_URL \
      $IMAGE \
      alembic upgrade head

- name: Deploy service
  run: kubectl set image deployment/api api=$IMAGE

Migration 跑完再 deploy。一次、單點、log 清楚。

Pattern B：Kubernetes Job

apiVersion: batch/v1
kind: Job
metadata:
  name: migrate-${VERSION}
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: myapp:${VERSION}
        command: ["alembic", "upgrade", "head"]

Deploy pipeline 先 kubectl apply 這個 Job，等它結束再 deploy Deployment。

Pattern C：init container (小心用)

spec:
  initContainers:
  - name: migrate
    image: myapp:${VERSION}
    command: ["alembic", "upgrade", "head"]
  containers:
  - name: api
    image: myapp:${VERSION}

每個 pod 啟動時跑一次 migration。解決了 health check 的問題 (init container 不計 readiness)，但沒解決多 replica 並發 migrate 的問題。除非你的 migration 都是 idempotent、且有外部鎖機制，否則 Pattern A/B 還是比較安全。

Dockerfile 應該長怎樣

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

# CMD 只負責起 service
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

不要在 CMD 裡做任何只該發生一次的事：migration、seed、cache warm-up、certificate fetch…… 這些都是 admin process / one-off job，跟 service process 切開。

例外：真的只有一個 replica

Hobby project、內部工具、只有一個 container 的小服務，CMD: migrate && server 是可以接受的簡化 — 如果你很確定以後也不會 scale 到 >1。一旦未來要 scale，就會踩前面三個雷，而重構時機通常挑得不好 (往往是 prod 正在燒的時候)。

小結

• Migration 跟 service start 不要放在同一個 CMD。
• 多 replica 同時 migrate 會死在 lock / health check / schema drift。
• 正解：CI/CD step、k8s Job，migration 是 one-off admin process。
• Twelve-Factor app 第六條 (Processes) + 第十二條 (Admin processes) 講的就是這個。

CI 上突然整片紅，每個 spec 只要 create(:product) (或任何會建 uploader 的 factory) 就噴：

Google::Auth::CredentialsError: keyfile not a valid file
# 或
Google::Auth::CredentialsError: credentials type '' is not supported

local 不會，因為 local 有完整的 GCS credentials file。CI 沒有，就爆。

表象先不談，根本原因是：uploader 在跑 spec 的時候試著連 GCS

聽起來很廢話，但按照一般 CarrierWave 的 test setup 應該不會這樣：

# spec/support/carrierwave.rb
CarrierWave.configure do |config|
  config.storage = :file
  config.enable_processing = false
end

理論上這個 global 設定會讓所有 uploader 在 test 環境用 local file。為什麼沒生效？

原因：class-level storage declaration 會 override global config

看一下你的 app 是不是有這種 uploader：

class UploaderBase < CarrierWave::Uploader::Base
  storage :gcloud        # ← 這一行
end

class FaviconUploader < UploaderBase
end

class SmsKycDocumentUploader < UploaderBase
  storage :gcloud        # ← 或這一行
end

storage :gcloud 在 class 定義時就把 _storage 變數寫死到該 class 上。CarrierWave 的 lookup 順序是：

1. instance 的 _storage
2. class 的 _storage ← 卡在這
3. parent class 的 _storage
4. global CarrierWave.configure

也就是說，只要 uploader class 裡有 storage :gcloud，global config 永遠搶不過 class-level。CarrierWave.configure 在 spec/support 裡設的 :file 對這些 class 完全無效。

為什麼 local 看起來沒事

local 環境 gcloud credentials file 是齊全的，所以即使真的走了 GCS 初始化路徑，也不會拋錯 — 只是在背景靜默連上 production bucket，你不會在 spec log 裡看到。

（是的，這代表你 local 跑 spec 的時候，可能在對 production GCS 打 request。這本身就該修。）

修法：spec land only，不要動 app code

不要改 uploader。改 uploader 容易出錯 (忘了 merge、env 判斷寫在 uploader 很醜)，也會影響 dev 環境的行為。

在 spec/rails_helper.rb 或 spec/support/carrierwave.rb：

RSpec.configure do |config|
  config.before(:suite) do
    # eager load，讓所有 uploader subclass 都被 Ruby 認得
    Rails.application.eager_load!

    # 強制所有 CarrierWave uploader 在 spec 走 :file
    CarrierWave::Uploader::Base.descendants.each do |klass|
      klass.storage :file
    end

    # 關掉 image processing，避免 spec 真的跑 MiniMagick
    CarrierWave::Uploader::Base.descendants.each do |klass|
      klass.enable_processing = false
    end
  end
end

這段做了什麼

1. eager_load!：development / test 預設是 autoload，不先 eager_load! 的話 descendants 只會看到已經 require 過的 uploader。
2. 走到每個 subclass 把 _storage 覆寫成 :file：這次是 class-level 寫入，就會蓋掉 uploader 檔案裡寫的 storage :gcloud。
3. enable_processing = false：關 image processing，spec 不會真的跑 thumbnail，快很多。

為什麼不用 CarrierWave.configure 就夠？

前面講過，class-level 的 storage :gcloud 搶在 global config 前面。global configure 只有對 沒宣告 storage 的 uploader 生效。

為什麼不用 ENV['RAILS_ENV'] 條件在 uploader 裡判斷？

class UploaderBase < CarrierWave::Uploader::Base
  storage(Rails.env.test? ? :file : :gcloud)
end

能動，但：

• uploader 開始背業務無關的環境判斷。
• CI 上要切換測試環境 (ex: integration test 真的要測 GCS) 時沒彈性。
• storage 呼叫時機是 class 定義期，某些 preloading 組合下會比 Rails.env 早。

比起這個，把測試策略放在 spec/support 是更乾淨的 separation of concerns。

順便：Active Storage 也有類似問題

Active Storage 用的是 config/storage.yml + config.active_storage.service，一般情況下：

# config/storage.yml
test:
  service: Disk
  root: <%= Rails.root.join("tmp/storage") %>

# config/environments/test.rb
config.active_storage.service = :test

這兩個沒齊全的話，test 也會跑到 production 的 service 名字。新開 project 時 check 一下。

小結

• CarrierWave class-level storage :gcloud 會 override 全域 test config。
• 修在 spec side：before(:suite) eager load + descendants.each { |k| k.storage :file }。
• 不要動 app code 裡的 uploader。
• CI 上「寫到 production bucket」這種事，local 可能看不出來；固定檢查 spec log 是不是有對外請求很重要。

SaaS 專案有一種很常見的需求：每個 tenant (shop / team / org) 自己填 API key。OpenAI / LINE Pay / ECPay 等等，各家第三方 API 的金鑰，不能寫死在 config/secrets.yml 或 ENV，因為每個 tenant 都不一樣。

最糟的實作是直接把金鑰明文存 DB：

create_table :shop_ai_credentials do |t|
  t.bigint :shop_id, null: false
  t.string :provider, null: false
  t.string :access_token   # ← 明文
  t.timestamps
end

這樣 DB backup 一外洩、DBA 一下 query、log 不小心吐出來，全部 tenant 的金鑰就全跟著走。

Rails 7.1+ 內建的 encrypts

Rails 7.1 之後直接支援 attribute-level encryption：

class ShopAiCredential < ApplicationRecord
  encrypts :access_token
end

底層會幫你處理加密 / 解密 / key rotation，相當方便。如果你的 Rails 夠新，直接用這個就好。

但如果你在 Rails 6/7.0、或因為別的原因不能用 encrypts，可以手刻一個基於 ActiveSupport::MessageEncryptor 的版本。

手刻版：MessageEncryptor

Migration

create_table :shop_ai_credentials do |t|
  t.bigint :shop_id, null: false
  t.string :provider, null: false
  t.text :access_token_encrypted     # 加密過的存這欄
  t.string :model
  t.timestamps
end

Model

class ShopAiCredential < ApplicationRecord
  belongs_to :shop

  def access_token
    return nil if access_token_encrypted.blank?
    encryptor.decrypt_and_verify(access_token_encrypted)
  rescue ActiveSupport::MessageEncryptor::InvalidMessage
    nil
  end

  def access_token=(plaintext)
    self.access_token_encrypted =
      plaintext.present? ? encryptor.encrypt_and_sign(plaintext) : nil
  end

  private

  def encryptor
    self.class.encryptor
  end

  def self.encryptor
    @encryptor ||= begin
      key = ActiveSupport::KeyGenerator
              .new(Rails.application.secret_key_base)
              .generate_key("shop_ai_credential.access_token.v1", 32)
      ActiveSupport::MessageEncryptor.new(key)
    end
  end
end

幾個要點

1. secret_key_base 當 master key。Rails 自己已經要求這是高熵隨機值，拿來 derive 沒問題。Production 走 credentials、env var、secret manager 都可以，重點是不要進 git。

2. KeyGenerator + salt。不要直接把 secret_key_base 塞給 MessageEncryptor。KeyGenerator 是 PBKDF2，會針對這個欄位的用途 derive 出獨立的 key。salt 帶版本號 ("v1")，之後要 rotate 時可以換 "v2" 做 migration。

3. encrypt_and_sign / decrypt_and_verify。用帶驗證的方法 (內部其實是 AES-GCM)，密文被竄改時 decrypt_and_verify 會拋 InvalidMessage，而不是默默吐出亂碼。

4. @encryptor memoize 在 class 層級。每次讀寫都重做 PBKDF2 會慢 (PBKDF2 就是設計來慢的)，memoize 到 process 記憶體就好。

5. rescue InvalidMessage 回 nil。某些情境下 (ex: secret_key_base 真的換了、或 DB 裡有歷史髒資料) 你會希望解密失敗時 app 不要整個爆掉。要不要 rescue 看需求 — 走 fail-fast 也合理。

表單端注意事項

Admin UI 常見需求是「編輯這張 credential 的模型設定，但不想強制重填金鑰」：

= form_with model: credential do |f|
  = f.password_field :access_token,
      placeholder: credential.access_token_encrypted.present? ? "已設定 — 留空則保留現有金鑰" : "輸入金鑰"

Controller 端：

def credential_params
  permitted = params.require(:shop_ai_credential).permit(:provider, :model, :access_token)
  permitted.delete(:access_token) if permitted[:access_token].blank?
  permitted
end

空字串就從 params 拿掉，access_token= setter 就不會被呼叫，access_token_encrypted 保留原值。

為什麼不用 symmetric encryption gem (ex: lockbox、attr_encrypted)

• 少一個 dependency，ActiveSupport::MessageEncryptor 已經在 Rails 裡，維護成本低。
• 需求簡單 (單一欄位、單一 purpose) 時，gem 的功能都用不到。
• gem 通常會綁自己的 key schema，之後要遷移到 Rails 7.1 encrypts 反而多一步。

如果你需要 blind index (加密後還能 query)、或 key rotation 自動化，gem 的功能才開始有價值。

不會保護你的東西

• Memory dump：程式跑的時候金鑰解密後在記憶體裡，root 存取 process 記憶體就看得到。
• Log 不小心印出來：Rails.logger.info credential.access_token 就前功盡棄，code review 要盯。
• secret_key_base 本身外洩：key 跟 ciphertext 一起外洩等於沒加密。最低限度：production 不把它放在 git、ideally 放進 secret manager (GCP Secret Manager、AWS KMS、Vault)。

小結

• Rails 7.1+：直接 encrypts :access_token。
• 7.0 以下：手刻一個 MessageEncryptor + KeyGenerator 包裝，30 行解決。
• 加密欄位命名帶 _encrypted 後綴，欄位型態用 text，不要用 string (密文比明文長)。
• log / inspect / as_json 要確認不會吐出明文或密文。

使用 paranoia (或 acts_as_paranoid、或自己手刻 deleted_at 欄位) 做 soft delete 的 Rails 專案，常會看到這種 migration：

create_table :shop_ai_credentials do |t|
  t.bigint :shop_id, null: false
  t.string :provider, null: false
  t.datetime :deleted_at
  t.timestamps
end

add_index :shop_ai_credentials, [:shop_id, :provider, :deleted_at], unique: true

邏輯上很合理：「同一個 shop 下同一個 provider 只能有一筆還活著的記錄。已刪除的 (deleted_at 有值) 不算。」

實際跑起來會發現：同一個 (shop_id, provider) 可以塞進多筆 deleted_at IS NULL 的 row。unique index 沒擋到。

原因：MySQL 把每一個 NULL 當成不同的值

SQL 標準規定 NULL != NULL (三值邏輯的 UNKNOWN)。MySQL 的 unique index 實作也是這樣：對 unique 檢查來說，每個 NULL 都是獨一無二的。

所以 [1, 'openai', NULL] 跟 [1, 'openai', NULL] 在 MySQL 看起來是兩個不同的 tuple，unique 檢查直接放行。

這個行為不是 bug，是規格。PostgreSQL 15 以前也一樣，PG 15 之後才加了 UNIQUE NULLS NOT DISTINCT 選項。MySQL 8.x 目前還沒有對應語法。

正確做法

拿掉 deleted_at，unique index 只管「活著的」場景：

add_index :shop_ai_credentials, [:shop_id, :provider], unique: true

然後刪除時不要真的 soft delete 相同 row，而是處理掉衝突。

但這樣會跟 paranoia 的 default scope 打架 — soft-deleted 的 row 還在表裡，第二次再插 [shop_id, provider] 會撞 unique。

有幾種常見解：

方法 A：刪除時同時改寫 provider

def soft_delete!
  update!(
    deleted_at: Time.current,
    provider: "#{provider}__deleted_#{SecureRandom.hex(4)}"
  )
end

讓歷史記錄保留，但 provider 欄位被「破壞」成不會撞到活著記錄的值。缺點：provider 欄位不再純粹，查詢歷史時要處理。

方法 B：硬刪除 (真的 DELETE)，另外留一張 audit 表

def destroy_with_audit!
  ShopAiCredentialAudit.create!(attributes)
  destroy!    # 真 DELETE
end

乾淨，但要多維護一張表。適合「歷史記錄不常查但要留」的情境。

方法 C：用 generated column

MySQL 5.7+ 支援 generated column，可以把 NULL 轉成穩定值：

ALTER TABLE shop_ai_credentials
  ADD COLUMN deleted_at_nn DATETIME
  AS (IFNULL(deleted_at, '1970-01-01 00:00:00')) STORED;

CREATE UNIQUE INDEX ix_shop_provider_deleted_nn
  ON shop_ai_credentials (shop_id, provider, deleted_at_nn);

活著的時候所有 row 都是 1970-01-01，撞到就擋；刪掉的時候 deleted_at_nn 變真實時間，各自獨立。

這方法保留了原始 schema 的語意，但 migration / schema.rb 會變醜，其他開發者不一定看得懂為什麼有個 _nn 欄位。

為什麼不選「在 application 層檢查」

跟前一篇 race condition 的結論一樣：application 層擋不住並發。兩個 request 同時過驗證、同時 INSERT，DB 沒有 unique constraint 的話，就兩筆都進去了。

paranoia + 並發寫 + 沒有正確的 unique index，production 一定會出現「同一個 shop 有兩筆 active 的同 provider credential」的髒資料，而且很難追。

檢查你現在的 schema

掃一下所有用 paranoia 的表，找出可疑的 unique index：

SELECT
  TABLE_NAME,
  INDEX_NAME,
  GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) AS cols
FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
  AND NON_UNIQUE = 0
GROUP BY TABLE_NAME, INDEX_NAME
HAVING cols LIKE '%deleted_at%';

每一列都值得檢查一次：這個 unique 真的有在擋嗎？

小結

• MySQL / 老版本 PG 的 unique index 對 NULL 是「每個 NULL 都不同」。
• [..., deleted_at] unique + paranoia 幾乎一定是 bug。
• 解法：要嘛刪除時改寫某欄位，要嘛用 generated column，要嘛硬刪除 + audit。
• 凡是用 soft delete 的表，schema review 一定要專門檢查 unique index。

有一張 shop_product_photos 表，需求是：「同一個 shop 下，圖片檔名要唯一」。很直覺地會寫：

class ShopProductPhoto < ApplicationRecord
  belongs_to :shop
  validates :filename, uniqueness: { scope: :shop_id }

  before_validation :ensure_unique_filename

  def ensure_unique_filename
    return unless filename_changed?
    base = filename
    i = 2
    while self.class.where(shop_id: shop_id, filename: filename).exists?
      self.filename = "#{base}_#{i}"
      i += 1
    end
  end
end

然後在 production 就會不定時 500：

ActiveRecord::RecordNotUnique: Mysql2::Error:
Duplicate entry 'photo_1-shop_42' for key 'index_shop_product_photos_on_filename_and_shop_id'

坑 1：TOCTOU — Time Of Check To Time Of Use

t=0  Request A: SELECT ... WHERE filename='photo_1' → 不存在
t=1  Request B: SELECT ... WHERE filename='photo_1' → 不存在
t=2  Request A: INSERT 'photo_1'  ← 成功
t=3  Request B: INSERT 'photo_1'  ← 撞 unique index，500

兩個 request 在 exists? 那一瞬間都看不到對方。Rails 的 validates_uniqueness_of 跟上面的 callback 都是這個 pattern，都擋不住這種 race。

坑 2：Primary / Replica Lag

Production 通常會把讀寫分流：寫走 primary，讀走 replica。ApplicationRecord 如果設定 connected_to role: :reading，exists? 可能跑到 replica。

t=0  Primary: INSERT 'photo_1' by Worker A     (commit)
t=1  Replica: (還沒 replicate 過來)
t=2  Worker B: exists? → 打 replica → false    (看不到 A 寫入)
t=3  Worker B: INSERT 'photo_1' → 撞 primary unique index，500

這不是 race condition，是 eventual consistency。幾十 ms 的 lag 就足夠中獎，而且比 TOCTOU 更難 reproduce。

真正的唯一性來源：DB unique index

Callback / validation 都只是 best effort，用來 UX 友善 (拒絕一些常見的重複、提早 fail) 。唯一性唯一可靠的保證是 DB 的 unique index。 寫 migration 時一定要加：

add_index :shop_product_photos, [:shop_id, :filename], unique: true

然後應用層要 預期 unique index 會撞到，並且處理它。

重試 + 改名的模式

class ShopProductPhoto < ApplicationRecord
  UNIQUE_FILENAME_INDEX = 'index_shop_product_photos_on_filename_and_shop_id'
  MAX_RETRIES = 10

  def save_with_unique_filename!
    base = filename.sub(/_\d+\z/, '')   # 把舊的 _N 剝掉重算
    taken = Set.new
    attempt = 0

    begin
      save!
    rescue ActiveRecord::RecordNotUnique => e
      raise unless e.message.include?(UNIQUE_FILENAME_INDEX)
      raise if (attempt += 1) > MAX_RETRIES

      taken << filename
      # 從 primary 重查一次，拿最新已存在的檔名
      existing = self.class.unscoped
                     .where(shop_id: shop_id)
                     .where('filename LIKE ?', "#{base}%")
                     .pluck(:filename)
      taken.merge(existing)

      i = 2
      i += 1 while taken.include?("#{base}_#{i}")
      self.filename = "#{base}_#{i}"

      retry
    end
  end
end

要點說明

1. 只 rescue 特定 index。RecordNotUnique 也會因為其他 unique index (ex: email) 觸發；亂 rescue 會把別的錯誤吞掉，所以要比對 message。
2. 把撞失敗的檔名也塞進 taken。replica lag 會讓 LIKE 查詢「看不到自己剛撞到的那個」，再跑一次就又挑到同一個名字。手動塞進去避免死循環。
3. MAX_RETRIES。沒有上限就是 DoS。10 次通常足夠，超過就是有別的問題 (真的有一萬個同名檔案？或者 bug)。
4. 一定要 primary 重查。Rails 6+ 可以 ApplicationRecord.connected_to(role: :writing) do ... end 強制走 primary。
5. _N 要剝掉重算。不然重試時會一路往上 (_2 → _2_2 → _2_2_2)。

為什麼不用 SELECT ... FOR UPDATE

兩個理由：

1. 鎖 shop_id 層級會把同一個 shop 的所有上傳串行化，上傳並發高的 shop 就卡住了。
2. 要鎖「不存在的 row」得用 gap lock / advisory lock，複雜度遠高於「rescue + retry」。

對這種「自動改名避開衝突」的需求，樂觀鎖 (optimistic) + retry 幾乎永遠比悲觀鎖 (pessimistic) 好。

測試怎麼寫

it 'retries on unique index violation' do
  create(:shop_product_photo, shop: shop, filename: 'photo_1')
  photo = build(:shop_product_photo, shop: shop, filename: 'photo_1')
  photo.save_with_unique_filename!
  expect(photo.filename).to eq('photo_1_2')
end

it 'does not retry on unrelated unique index' do
  # 模擬別的 index 撞到
  allow(photo).to receive(:save!).and_raise(
    ActiveRecord::RecordNotUnique.new('Duplicate entry for index_on_email')
  )
  expect { photo.save_with_unique_filename! }.to raise_error(ActiveRecord::RecordNotUnique)
end

it 'raises after MAX_RETRIES' do
  allow(photo).to receive(:save!).and_raise(
    ActiveRecord::RecordNotUnique.new("... #{ShopProductPhoto::UNIQUE_FILENAME_INDEX} ...")
  )
  expect { photo.save_with_unique_filename! }.to raise_error(ActiveRecord::RecordNotUnique)
end

至少覆蓋：初次成功、撞一次改名、撞到別的 index 不重試、超過上限拋出。

小結

• validates_uniqueness_of 不保證唯一性，DB unique index 才保證。
• Callback 幫忙的是 UX (常見場景提早 fail)，production 還是會撞 RecordNotUnique。
• 處理方式：rescue 特定 index + retry + 改名 + 上限。
• primary/replica 分流的架構，重試時要強制走 primary 查資料。

當你在一個已經跑了很多年的 Rails + MySQL 專案加一張新表，然後很直覺地寫：

create_table :shop_ai_credentials do |t|
  t.references :shop, null: false, foreign_key: true
  t.string :provider, null: false
  t.timestamps
end

在新建的 local 環境可能沒事，但 deploy 到 production 會在 migration 那一步死掉，錯誤訊息類似：

Mysql2::Error: Referencing column 'shop_id' and referenced column 'id'
in foreign key constraint ... are incompatible.

原因

t.references :shop 在 Rails 5.1+ 預設會建 bigint。但如果你的 shops.id 是很久以前建的，欄位型態很可能是 int 而不是 bigint。MySQL 建 foreign key 時會嚴格檢查兩邊欄位型態必須完全一致，int 跟 bigint 就會被擋下來。

local 可能沒事是因為你是用最新的 schema 從零跑 migration，shops.id 一開始就是 bigint。production 則是歷史遺物。

修法

有兩個方向：

1. 不加 DB-level 的 FK，只在 model 層用 belongs_to

create_table :shop_ai_credentials do |t|
  t.bigint :shop_id, null: false
  t.string :provider, null: false
  t.timestamps
end

add_index :shop_ai_credentials, :shop_id

class ShopAiCredential < ApplicationRecord
  belongs_to :shop
end

Referential integrity 從 DB 移到 app 層。優點：不用動 shops 表、deploy 零風險。缺點：如果有別的系統 (data pipeline、直接跑 SQL 的人) 繞過 Rails 寫資料，就保證不了了。

2. 先把 shops.id 升級成 bigint

這是正解，但成本高。要：

• 確認 shops.id 沒有其他表以 int 型態參照它 (每個參照方都要一起升級，不然同樣撞 FK 型態錯誤)。
• 跑一支 migration 改 column type。大表會鎖很久。
• 測 replication 是否跟得上。

小專案可以做，大表 + 多 FK 的老專案通常不值得。

為什麼不要留 foreign_key: true + rescue

有些人會想「那我包 begin/rescue 先試看看」。不要。migration 失敗後 schema 會停在半套狀態，下一次 deploy 會更麻煩。decision 要在寫 migration 當下就做：要嘛確認兩邊都是 bigint，要嘛就不加 DB FK。

順便：欄位 index 也要自己加

t.references 會自動加 index，但 t.bigint :shop_id 不會。記得手動：

add_index :shop_ai_credentials, :shop_id

如果還有複合 unique index (ex: [shop_id, provider])，單欄 shop_id index 還是要保留。MySQL 複合 index 只在前綴欄位可以被單欄查詢利用，但有些 ORM 產生的 query 不一定會打到前綴，留一個獨立的 shop_id index 最保險。

小結

• t.references 在新專案很好用，老專案要先確認對面 id 欄位型態。
• 用 t.bigint :shop_id + belongs_to 是最務實的妥協：DB 不加 FK、model 負責關聯。
• 別忘了手動加 add_index 跟複合 unique index。

這幾個詞常混用，先分清楚：

1. Deep Link — 任何可以「打開 app 到特定畫面」的連結都算，包含 custom scheme (myapp://order/123) 與 https link。
2. Universal Links (iOS) — 用 https:// 連結打開 app 的機制，沒裝 app 就 fallback 到網頁。
3. App Links (Android) — 類似 Universal Links 的 Android 版本，需要 Digital Asset Links 驗證。
4. Custom URL Scheme — 早期的 myapp:// 作法，不需 domain 驗證，但 iOS/Android 都不保證安全。

在 Expo 裡，三種都可以做，只是設定方式不一樣。

Custom Scheme (最簡單)

app.json / app.config.js 設定：

{
  "expo": {
    "scheme": "myapp"
  }
}

打開 myapp://order/123 就會進到 app。測試用可以，但正式環境建議改用 Universal Links / App Links，因為 custom scheme 在 email、SMS、社群平台常會被攔截或不可點。

iOS Universal Links

要讓 https://example.com/order/123 直接打開 app，需要三件事：

1. Associated Domains capability 要打開。Expo 設定：

    {
      "expo": {
        "ios": {
          "associatedDomains": ["applinks:example.com"]
        }
      }
    }
   

2. Apple App Site Association 檔案 要放在：

    https://example.com/.well-known/apple-app-site-association
   

   內容：

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appID": "TEAMID.com.yourcompany.yourapp",
            "paths": ["/order/*", "/product/*"]
          }
        ]
      }
    }
   

   注意：這個檔案 不能加副檔名，而且必須 Content-Type: application/json，HTTPS 回 200。

3. iOS 第一次啟動 app 時會 fetch 這個檔案，之後就認得這個 domain。

Android App Links

Expo 設定：

{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            { "scheme": "https", "host": "example.com", "pathPrefix": "/order" }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

然後 web 端放：

https://example.com/.well-known/assetlinks.json

內容：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourcompany.yourapp",
      "sha256_cert_fingerprints": ["AA:BB:CC:..."]
    }
  }
]

sha256_cert_fingerprints 是你的簽章憑證 SHA-256 指紋，用 eas credentials 可以查。

路由側處理 (Expo Router)

Expo Router 會自動把 https/app link 的 pathname 對應到 route。例如 /order/123 打開 app，會進 app/order/[id].tsx，完全不用額外寫 linking config。

如果沒用 Expo Router，就要自己用 Linking.getInitialURL() 跟 Linking.addEventListener('url', ...) 處理：

import * as Linking from 'expo-linking';
import { useEffect } from 'react';

export function useDeepLink(onUrl: (url: string) => void) {
  useEffect(() => {
    Linking.getInitialURL().then((url) => {
      if (url) onUrl(url);
    });
    const sub = Linking.addEventListener('url', ({ url }) => onUrl(url));
    return () => sub.remove();
  }, [onUrl]);
}

常見踩雷

1. apple-app-site-association 要放在 root domain，不能放 subdirectory。
2. iOS 會 cache，改完檔案之後不一定馬上生效；重裝 app 最保險。
3. Android autoVerify 失敗 = 走不到 deep link。要在系統 log 看 PackageManager 的驗證結果，常見原因是 assetlinks.json 回 301、回 HTML、Content-Type 錯、或 SHA-256 指紋對不上 (debug vs release key)。
4. iOS 上從 Safari 手動打 URL 不會觸發 Universal Link，要從別的 app (iMessage、Notes) 點才行。這不是 bug，是 Apple 設計。
5. 沒裝 app 時的 fallback — 兩邊 OS 都會自動開瀏覽器載入該 https URL，所以 web 端最好也能處理同一個 path。

小結

Deep link 要打通的話，app 端設定其實不多，主要麻煩都在 domain 這側的兩個檔案 (apple-app-site-association 跟 assetlinks.json)，跟驗證流程。第一次踩都會在這裡花最多時間，設定好之後就是單純的路由對應問題了。