Next.js 1 つで動いていたサイトを、Go のマイクロサービス ＋ React（Vite）＋ 自宅 Mac mini の Kubernetes に置き換えた。
このドキュメントでは、何をどう作ったかを図を使って順番に説明する。

図は Mermaid という書き方で描いてあり、GitHub や VS Code のプレビューで絵として表示される。

目次

第0回 全体像：何から何に置き換えたか

置き換え前：Next.js 1 つ

Next.js は「画面（React）」と「サーバーの処理（API）」を 1 つのプロジェクトにまとめて書ける。手軽だが、全部がくっついているので、一部を直しても全体を作り直して入れ替えることになる。

置き換え後：役割ごとに分割

8 つの Go サービス

1 回のアクセスを追う：「勤務場所」ページ

リプレイス全体の方針

• 見た目と作りは変えるが、内容は 1 文字も変えない：文言・URL・メール文面・localStorage のキーは旧版のまま
• URL を変えない：Google に登録済みのログイン用 URL（/api/auth/*・/api/calendar-sync/*）は旧版と同じ
• 旧版と同じ答えを出すことをテストで守る：旧 TypeScript を Node で動かして作った正解データ（golden）と照合する
• いきなり全員に出さない：dev → stg → 本番の順。本番は 10% の利用者から少しずつ切り替える

第1回 通信の約束事：Protocol Buffers・Connect・gRPC

なぜ必要か

画面（TypeScript）とサーバー（Go）は別の言語で書かれている。「関数の名前」「渡すもの」「返ってくるもの」の約束がずれると動かない。
そこで約束を 1 つのファイル（.proto） に書き、両方のコードをそこから自動で作る。

用語

約束事の例（backend/proto/taramanji/worklocation/v1/worklocation.proto）

service WorkLocationService {
  rpc ListWorkLocations(ListWorkLocationsRequest) returns (ListWorkLocationsResponse) {} // 公開
  rpc SetWorkLocations(SetWorkLocationsRequest) returns (SetWorkLocationsResponse) {}   // 管理者
  rpc DeleteWorkLocation(DeleteWorkLocationRequest) returns (DeleteWorkLocationResponse) {}
  rpc GetWorkLocation(GetWorkLocationRequest) returns (GetWorkLocationResponse) {}      // 内部（reservation から）
}

// @entity
message WorkLocation {
  // @pk
  string date = 1;      // YYYY-MM-DD（JST）
  // @required
  string location = 2;
}

// @entity などのコメントは自作の生成器（第3回）への指示。

URL の形

RPC 1 つが URL 1 つになる：/<package>.<Service>/<RPC名>

POST /taramanji.worklocation.v1.WorkLocationService/ListWorkLocations
content-type: application/json

{}

手元なら curl でも呼べる（backend/README.md）。

1 つのサーバーで 3 種類の呼ばれ方を受ける

backend/pkg/util/server/server.go で、1 つのポート（:8080）が HTTP/1 と h2c の両方を受けるように設定している。

protocols := new(http.Protocols)
protocols.SetHTTP1(true)
protocols.SetUnencryptedHTTP2(true)

設定ファイル

• backend/buf.yaml：lint は STANDARD（空のレスポンスを許すため 1 ルールだけ除外）
• backend/buf.gen.yaml：3 つの生成器（protoc-gen-go・protoc-gen-connect-go・mss-protoc-gen）
• frontend/buf.gen.yaml：protoc-gen-es。notification は内部専用なので画面側には生成しない

第2回 層の分け方：DDD ＋ クリーンアーキテクチャ

考え方

• DDD（ドメイン駆動設計）：業務の言葉（勤務場所・予約・お問い合わせ）で区切って作る。区切りを「コンテキスト」と呼び、ここでは 1 コンテキスト = 1 サービス
• クリーンアーキテクチャ：コードを層に分け、依存（import）は外側から内側への一方通行にする。業務ルールが Redis や HTTP の都合に引きずられない

ポイントは、内側は interface（「こういう関数があるはず」という約束）だけを知っていること。本物の Redis かテスト用の偽物かは、起動時（cmd/<service>/main.go）に差し込む。これを DI（依存性の注入） という。

worklocation のファイル一覧

人が書くのは業務ルールと usecase だけで、残りは proto から生成される。

1 リクエストが層を通る順番

手書き部分の中身

業務ルール（domain/service/work_location_service.go）。旧 Next.js の src/app/api/location/route.ts と同じ動きを Go で書き直したもの。

const Undecided = "未定（お問い合わせください）"
// ListPublished は過去の日を消し、今日から 2 ヶ月先まで未登録の日を Undecided で埋めて返す。
today := jst.Date(now)
// ... 過去の日は BulkDelete
// JS の setMonth(+2) と同じく、月末の繰り越しも Go の AddDate と一致する
last := jst.Date(now.In(jst.Location).AddDate(0, publishMonths, 0))

usecase（usecase/work_location_usecase.go）：

if len(input.Dates) == 0 || input.Location == "" {
    return nil, errs.NewCodedError(errs.ErrorTypeBadRequest, "missing_fields", "日付と勤務場所を指定してください")
}

起動（cmd/worklocation/main.go）：部品を組み立てるだけ。

rdb, _ := redisx.New(serviceName)
svc := service.NewWorkLocationService(infrarepo.NewRedisWorkLocationRepository(rdb), nil)
handlers := di.NewHandlers(usecase.NewWorkLocationUsecase(svc))
adminOnly := auth.AdminInterceptor([]string{ /* Set と Delete */ }, nil, "")
server.Run(serviceName, func(mux *http.ServeMux) {
    handlers.Register(mux, connect.WithInterceptors(adminOnly))
})

データの持ち方の変化

第3回 自作のコード生成・エラー・ログイン・Redis

mss-protoc-gen（backend/cmd/mss-protoc-gen/）

protoc の プラグイン（生成器）を自作したもの。proto のコメント（アノテーション）を読んで、層ごとの雛形を作る。

buf.gen.yaml で渡しているオプション：contexts=true（internal/<context>/ に出し分け）、infra=redis、handler=connect。

cd backend
make install-tools   # buf と生成器を入れる
make proto-gen       # proto を変えたら必ず実行

*.gen.go と gen/ は手で直さない。直したいときは proto を変えて生成し直す（CI でも「生成し直して差分が出ないか」を見ている）。

エラーの扱い（backend/pkg/util/errs/）

code（invalid_email など）には旧 API のエラー文字列をそのまま使う。フロントはそれを見て旧版と同じメッセージを出す。

ログイン（backend/pkg/util/auth/）

• JWT：中身（メールアドレスなど）に署名を付けた文字列。署名の鍵 AUTH_SECRET は全サービスで共通なので、identity に問い合わせなくても各サービスが自分で確かめられる
• Interceptor：全 RPC の手前に挟まる関所。管理者用の RPC だけを止める
• 5 分ごとの同期（CronJob）は人ではないので、Cookie の代わりに Authorization: Bearer <トークン> で通す

Redis の分け方

• 1 つの Redis を、DB 番号と**ユーザー（ACL）**で区切って使う
  • DB 0 = worklocation、1 = content（キャッシュ）、2 = calendarsync
  • 各サービスのユーザーは自分のキー（例 workLocations:*）しか触れず、危険なコマンドも使えない
• 実際の区切りは REDIS_URL（redis://<ユーザー>:<パスワード>@<ホスト>:6379/<DB番号>）で決まり、その値は deploy/k8s/scripts/make-secrets.sh が作る

その他の共通部品（backend/pkg/util/）

第4回 サービス同士の通信・外部 API・テスト

サービス同士：interface を挟んで gRPC

// backend/internal/inquiry/infra/gateway/notification_client.go
notificationv1connect.NewNotificationServiceClient(
    server.InternalHTTPClient(), baseURL, server.InternalClientOptions()...) // WithGRPC()

reservation → worklocation（その日の勤務場所を聞く）も同じ形。

外部 API の担当

外部の URL を勝手に取りに行かないよう、Qiita とマップは許可したホストだけを通す（IsQiitaURL・IsMapsURL）。

旧 API との対応

テスト

コンテナイメージ（backend/Dockerfile）

1 つの Dockerfile で、--build-arg SERVICE=reservation のように 8 サービスを作り分ける。

第5回 Docker と Kubernetes の基本、kind

コンテナと Kubernetes

kind で Mac mini の中にクラスターを作る

kind = Kubernetes in Docker。Docker のコンテナ 1 つを 1 台のマシンに見立てる。

• deploy/kind/cluster.yaml：1 + 2 台。GKE と同じ「ゾーン」のラベルを付け、Pod を 2 台に散らす練習ができる
• データ置き場を Mac のフォルダに出しているので、クラスターを作り直してもデータが残る（StorageClass standard-rwo、Retain）
• deploy/kind/up.sh：起動（Mac の起動時に launchd が実行）。cloud-provider-kind で LoadBalancer に IP を付ける
• deploy/kind/platform.sh：GKE なら最初からあるもの（metrics-server・Envoy Gateway・StorageClass）を入れる

Go サービス 1 つ分のマニフェスト（deploy/k8s/base/apps/worklocation.yaml）

第6回 入口：Cloudflare・Envoy Gateway・HTTPRoute

ルーターのポートを開けずに公開する

• Cloudflare Tunnel：家の中の cloudflared が外へつなぎに行く。外から家へ入る穴（ポート開放）が要らない
• トンネルは 2 本

• ホスト名が dev01-gws.taramanji.com のようにハイフンなのは、Cloudflare の無料証明書 *.taramanji.com が 1 段しか効かないから

Envoy Gateway と HTTPRoute

Gateway API は Kubernetes の「入口」の標準の書き方。Envoy Gateway はその実装。

• notification には HTTPRoute が無い → 外からは絶対に届かない
• 各ルールは <svc>（重み 100）と <svc>-canary（重み 0）の 2 つに向いている。カナリアのとき Argo Rollouts がこの重みを書き換える（第9回）
• ホスト名は base では仮の値で、環境ごと（overlay）に差し替える

第7回 Redis・Secret・NetworkPolicy

Redis（deploy/k8s/base/data/redis.yaml）

• StatefulSet：Pod に固定の名前（redis-0）と専用のディスクを付ける。データを持つものに使う
• AOF（appendonly yes、1 秒ごとに書き出し）で、再起動してもデータが残る
• maxmemory 200mb・noeviction：あふれたら勝手に消さずにエラーにする

Secret：公開リポジトリに鍵を置く方法

• 暗号を解く鍵はクラスターの中にしかないので、暗号文は public リポジトリに置いてよい
• dev01〜03 は同じ secrets/dev/ を、namespace だけ変えてそれぞれ暗号化する（SealedSecret は namespace ごとに別の暗号になるため）

deploy/k8s/scripts/make-secrets.sh dev
for e in dev01 dev02 dev03; do deploy/k8s/scripts/seal.sh $e; done

• CI（lint）は、平文の kind: Secret がコミットされていないかも確かめる

NetworkPolicy：Pod 同士の通信も「許可したものだけ」

まず全部を拒否（default-deny-ingress）し、必要な道だけを開ける。

第8回 CI/CD と GitOps（dev01〜03 を含む）

用語

環境は 5 つ

全体の流れ

変わったサービスだけ作り直す（deploy/k8s/scripts/changed-services.py）

dev01〜03：PR ごとに枠を割り当てる（今回の変更）

以前の dev は 1 つで、PR が来るたびに上書きされていた。今は 3 つの枠があり、deploy/k8s/scripts/pick-dev.sh が出す先を決める。

例：PR が A・B・C・D の順に来た場合

• 「まず stg にそろえる」のは、前にその枠を使っていた PR の版が残らないようにするため
• 全部の反映ジョブは同じ concurrency グループ（deploy-manifests）なので、2 つの PR が同じ枠を同時に取り合うことはない
• 今どこに何が出ているか：PR のコメント、git log --grep '^deploy(dev0'、Argo CD の画面（taramanji-dev01〜03）

dev・stg の共通部分（deploy/k8s/components/nonprod/）

• dev・stg も Rollout（カナリアの手順なし）にしたので、rollouts.taramanji.com で namespace を taramanji-devNN / taramanji-stg に切り替えれば入れ替わりの様子が見える
• Rollouts の画面は、開いたときに taramanji の一覧が出るよう --namespace=taramanji を付けた（deploy/gitops/rollouts-values.yaml）
• dev・stg の Redis はそれぞれの namespace に 1 つずつ。予約・お問い合わせは本物の GAS・SES に届くので、試すときは自分宛てに

Argo CD の構成

• ApplicationSet：1 つの雛形から複数の Application を作る仕組み。ここでは {env} に dev01〜03 を入れて 3 つ作る
• 自動同期（prune：Git から消したら消す、selfHeal：手でいじったら戻す）
• 家の回線は遅いので、git の待ち時間を 300 秒に伸ばしている
• deploy/gitops/bootstrap.sh の順番：Sealed Secrets → Argo Rollouts → Argo CD → リポジトリの鍵 → root

今回の修正：deploy/gitops/argocd-values.yaml に applicationSet: enabled: false と書いてあったが、使っているチャート（argo-cd 10.9.6）にはこの項目が無く、ApplicationSet コントローラーは最初から動いていた（だから dev01〜03 が作られている）。書いてあることと実際が逆で紛らわしいので、replicas: 1 と説明コメントに直した。helm template で比べて、クラスターに入る中身は変わらないことを確認済み。

本番リリース

# stg で確かめたコミットにタグを付ける
git tag v1.2.3 <コミット> && git push origin v1.2.3

戻すとき（Git が正なので、Git を戻す）：

deploy/k8s/scripts/set-version.sh prod v1.2.2 reservation
git commit -am "deploy(prod): rollback reservation to v1.2.2" && git push

第9回 カナリアリリース：Argo Rollouts ＋ Datadog

カナリアとは

新しい版を一部の利用者にだけ先に出し、問題がなければ広げる。炭鉱のカナリアが由来。

仕組み

• 新版だけを判定できるのは、各 Pod に version タグ（＝イメージのタグ）が付いているから。Kustomize の replacements で、イメージのタグを Datadog のラベルと判定の引数に自動でコピーしている
• 判定に入れないもの
  • ヘルスチェック：数秒ごとに来るので、混ぜると数字が実態から離れる（server.go でトレースしない）
  • 外部 API への呼び出し：自分の失敗ではないので、サーバー側の span だけを見る（DD_TRACE_SPAN_ATTRIBUTE_SCHEMA=v1）
  • RunSync の遅さ：カレンダー同期はもともと長いので p95 の判定から外す
• web は一度に切り替える：旧版の HTML から新版の JS を取りに行くと 404 になるため、混ぜない

操作

kubectl argo rollouts --context kind-taramanji -n taramanji get rollout reservation --watch  # 様子
kubectl argo rollouts --context kind-taramanji -n taramanji promote reservation              # 10% から先へ
kubectl argo rollouts --context kind-taramanji -n taramanji abort reservation                # 中止して戻す

画面なら https://rollouts.taramanji.com（Cloudflare Access で管理者だけ）。

監視（deploy/k8s/observability/）

• monitors.py：5xx 率・p95・再起動・トンネルの接続数・Redis のメモリ・カレンダー同期の失敗・予約やメールの失敗・証明書の期限・Argo の異常など
• dashboard.py：入口から Redis まで、上から順に見られるダッシュボード
• dev・stg のログは取らない（お金がかかるため）。トレースは届く

第10回 Next.js から React ＋ Vite へ、FSD

何が変わったか

• サーバー側の処理（API・ログイン）は全部 Go へ移ったので、フロントは画面だけになった
• 内容は 1 文字も変えないのがルール。文言・リンク・検証メッセージ・localStorage のキーは旧版のまま。/privacy と /calendar-sync は Google の審査に登録済みなので特に厳密

主な設定ファイル

• frontend/vite.config.ts：@ を src の別名に。開発時は API（/taramanji.* と /api）を kind の Gateway へ転送し、Host を dev01.taramanji.com にする（＝手元の開発は dev01 のデータを使う）。GATEWAY_URL で変更可
• frontend/src/shared/config/site.ts：今いるホスト名から環境を判断（dev01〜03・stg・prod）。dev・stg ではタブのタイトルに [DEV01]〜[DEV03]・[STG] が付く
• frontend/src/app/routes/router.tsx：ページは必要になってから読み込む（lazy）。gws のホストでは /admin だけを出す（旧 middleware.ts の役目）

FSD（Feature-Sliced Design）：フォルダの分け方

ルール（npm run lint:fsd = scripts/check-fsd.mjs が CI で検査）：

1. import は上から下へだけ
2. 同じ層の別のスライスは import しない（例：features/contact から features/reserve は ✕）
3. 他のスライスは index.ts で公開したものだけを使う

例：src/entities/work-location/index.ts

export * from "./model/locations";
export { useWorkLocations } from "./api/use-work-locations";

第11回 データの取り方と状態

API の呼び出し：connect-es

関数のように呼べて、引数や戻り値の型を間違えるとビルドで止まる。エラーは toApiError(err)（src/shared/api/errors.ts）で { code, message, detail, fields } にし、code を見て旧版と同じ文言を出す。

状態の置き場所

サーバーのデータ（src/entities/work-location/api/use-work-locations.ts）：

export function useWorkLocations() {
  return useQuery({
    queryKey: ["work-locations"],
    queryFn: async () => (await workLocationApi.listWorkLocations({})).locations,
  });
}

フォームの入力（src/features/contact/model/state.ts）：

const ttlString = createTTLStorage<string>(10 * 60 * 1000);
export const contactEmailAtom = atomWithStorage<string>("contact_email", "", ttlString, { getOnInit: true });

入力チェック：zod

補足：package.json には react-hook-form も入っているが、実際のコードでは使っていない。フォームの値は jotai に置き、送信時に zod の safeParse で確かめている。useMutation も使わず、API を直接呼んで try/catch している。

第12回 見た目と動き、配信

見た目

決めごと（frontend/CLAUDE.md）：

• ダークテーマ固定。文字はすべてコントラスト 4.5:1 以上（npm run check:contrast が Playwright で全ページを測る）
• 飾りのアイコン・絵文字・グラデーションを付けない。何でも箱で囲まない
• 残すもの：背景に流れる CLI コマンド、送信中のターミナル風ダイアログ、Qiitan / Gopher、所属とスキルの色分け

動き（motion ライブラリ、src/shared/ui/motion/）

すべて prefers-reduced-motion（OS の「動きを減らす」設定）で止まる。

配信と計測

• リリース直後に古いタブが消えた JS を取りに行って失敗したら、1 回だけ自動で再読み込みする（src/shared/lib/stale-chunk.ts）
• Datadog RUM（src/app/providers/rum.ts）：ブラウザでの体験を計測。traceparent を付けて、ブラウザ → Gateway → Go まで 1 本のトレースでつながる
• ページビューは navigator.sendBeacon("/api/metrics/pageview") → analytics → Datadog の web.pageviews

付録

用語集

ドキュメントと実装の食い違い（調べて分かったこと）