管理画面フォーマット開発編 #4
Server Actionで実装するアバター画像のアップロードと表示

ユーザープロフィールに欠かせないアバター画像を、安全にアップロード・表示する仕組みを構築

初回公開日2025/9/16

最終更新日2025/9/16

0. はじめに

これまで「管理画面フォーマット開発編」シリーズでは、ログイン機能とコンテキストを利用したユーザ情報の表示までを整えました。

今回のテーマは、ユーザプロフィールに欠かせない アバター画像のアップロードと表示 です。単純に「画像を保存して表示する」だけであれば難しくありませんが、本プロジェクトでは以下の要件を満たしたいと考えています。

画像は外部から直接アクセスできないよう保護すること
必ず認証・認可を通じて配信されること
将来的な拡張（CDNや外部ストレージ利用）にも対応できる設計であること

特に「画像を静的ファイルとして公開する」のではなく、Server Action を基盤にした仕組み でアップロードから配信までを扱う点が重要です。これにより、セッション情報やRBACロジックを統一的に適用でき、APIを最小化してセキュリティリスクを減らすことができます。

本記事では、Prismaのスキーマ拡張による User テーブルへの avatar カラム追加から、サーバ上への保存処理、Shadcn/ui を利用したフォーム実装まで、アバター機能を安全に構築する流れを整理します。シリーズを通じて積み上げてきた 認証・認可の基盤 と一体化させることで、現場でも安心して利用できるユーザプロフィール管理を完成させていきます。

技術スタック

Tool / Lib	Version	Purpose
Ubuntu	24.04 LTS	WebサーバOS
Nginx	1.28.x	Webサーバ
React	19.x	UIの土台。コンポーネント/フックで状態と表示を組み立てる
Next.js	15.x	フルスタックFW。App Router/SSR/SSG、動的ルーティング、メタデータ管理
TypeScript	5.x	型安全・補完・リファクタリング
shadcn/ui	latest	RadixベースのUIキット
Tailwind CSS	4.x	ユーティリティファーストCSSで素早くスタイリング
Zod	4.x	スキーマ定義と実行時バリデーション

本記事では、前回の記事 【管理画面フォーマット開発編 #3】AuthProviderでログイン済みユーザー情報を全体共有 までのソースコードを引き継いで追加・編集していきます。

1. アバター画像機能の要件整理

アバター画像は「プロフィール編集の見た目を整える」だけではなく、セキュリティや将来の拡張性にも関わる要素です。ここでは、システムに組み込む際に押さえておくべき要件を整理します。

認証必須の配信（Next.js経由・直リンク禁止）

アバター画像は /var/www/private/avatars/ に保存されますが、このディレクトリは外部公開しません。必ず Next.js の Route Handler を通じて、Cookieベースのセッション検証とRBACを経由したユーザーだけに配信します。
直リンクでアクセスできてしまうと、認証を回避して画像が閲覧されるリスクがあるため、この設計が不可欠です。

txt

[ブラウザ] → [Next.js Route Handler] → [認可チェック] → [ファイル読込] → [レスポンス]
                   ↑ 直リンクは禁止（Nginx経由で弾く）

保存先と命名（/var/www/private/avatars/ ＋ UUID.ext）

ファイル名は UUID＋拡張子 とし、衝突や予測を避けます。拡張子は Content-Type 判定のため保持します。
保存ディレクトリも固定し、コード中でパスを組み立てやすくします。

txt

例: /var/www/private/avatars/
     ├─ 550e8400-e29b-41d4-a716-446655440000.png
     └─ 1c6f3b32-88b3-44b9-bc42-33d9a9c541a4.webp

APIは作らない（Server Actionとリソース配信ルートのみ）

今回の実装では API Route を新規に作りません。アップロードは Server Action、表示は Route Handler で完結させます。これによりエンドポイントの種類を最小化し、セキュリティリスクを減らします。

要件を整理した一覧

以下の表に、今回のアバター機能で必須とする要件をまとめます。

区分	要件内容	理由
配信	Next.js 経由（Route Handler）	認証・認可を統一的に適用するため
直リンク	禁止（Nginxレベルで遮断）	セッション検証を回避されるのを防ぐため
保存ディレクトリ	`/var/www/private/avatars/`	外部から直接参照できない安全なパス
命名方式	`UUID + 拡張子`	衝突防止・推測困難・Content-Type判定用
アップロード	Server Action	APIを増やさず認可チェックを一元管理
表示	`/avatar/[userId]` ルート	配信専用の仕組みに限定し安全に返却

2. Prismaスキーマへの拡張

アバター機能を扱うために、まずは User テーブルへ新しいカラムを追加します。ここでは、スキーマ修正と既存コードへの影響を整理し、必要な修正箇所を実際に示していきます。

User.avatar を追加する理由

アバター画像は各ユーザが 1 つだけ保持する想定です。そのため別テーブルに切り出さず、最小構成として User モデルに avatar カラムを追加します。
このカラムには 保存先ディレクトリに置かれたファイル名（UUID＋拡張子） を格納し、実際の配信時に組み合わせて利用します。

txt

Userテーブルのイメージ

| id (UUID) | name     | email              | roleId | avatar                          |
|-----------|----------|-------------------|--------|---------------------------------|
| U001      | 山田 太郎 | taro@example.com  | R001   | 550e8400-e29b-41d4.png          |
| U002      | 佐藤 花子 | hanako@example.jp | R002   | 1c6f3b32-88b3-44b9.webp         |

Prismaスキーマの修正

prisma/schema.prisma の User モデルへ avatar カラムを追加します。

prisma

model User {
  id        String    @id @default(uuid())
  displayId String    @unique @default(dbgenerated("generate_display_id('user_display_id_seq','US')")) @db.VarChar(10)
  isActive  Boolean   @default(true)
  createdAt DateTime  @default(now()) @db.Timestamptz
  updatedAt DateTime  @updatedAt      @db.Timestamptz
  deletedAt DateTime?                  @db.Timestamptz

  departmentId     String
  roleId           String
  email            String
  hashedPassword   String
  name             String
  phone            String?
  remarks          String?

  failedLoginCount Int       @default(0)
  lockedUntil      DateTime? @db.Timestamptz

  // ★ 新規追加
  avatar           String?   // UUID＋拡張子を格納

  department Department @relation(fields: [departmentId], references: [id], onDelete: Restrict)
  role       Role       @relation(fields: [roleId], references: [id], onDelete: Restrict)
  sessions   Session[]  @relation("UserSessions")

  @@unique([departmentId, email])
  @@index([departmentId])
  @@index([roleId])
  @@index([isActive])
  @@index([createdAt])
}

この変更後は、必ずマイグレーションとクライアント生成を実行します。

zsh

npx prisma migrate dev --name add_user_avatar
npx prisma generate

ただし、本番環境では migrate dev ではなく migrate deploy を使うことを推奨します。 dev コマンドは破壊的な変更を検出したときに DB をリセットする場合があるため、本番では安全にマイグレーションを適用するために deploy を利用します。

既存コードへの影響と修正

User.avatar の追加に伴い、アプリ全体の型や処理に影響が及びます。以下に主な修正箇所を表形式で整理します。

ファイル	修正内容
src/lib/auth/user-snapshot.ts	avatarUrl を DB の avatar から組み立てる処理に変更
src/lib/auth/types.ts	AuthUserSnapshot の avatarUrl 型はそのまま利用可能
src/components/sidebar/nav-user.tsx	そのまま利用可能、テーブルに値があるときだけDB由来、なければモック値 (/user-avatar.png) を利用
src/components/profile/profile-form.tsx	保存完了後に setUser() を呼び出して avatar を即時反映（次章以降で解説）

getUserSnapshot（src/lib/auth/user-snapshot.ts）の修正

これまで avatarUrl を常に null で返していましたが、DB の値を利用するよう変更します。

// src/lib/auth/user-snapshot.ts
import { prisma } from "@/lib/database";
import type { AuthUserSnapshot } from "./types";

/**
 * セッションで得られた userId から、Context 用の最小スナップショットを作る。
 * PII を最小化し、重い JOIN は避け、必要な列だけ select する。
 */
export async function getUserSnapshot(
  userId: string,
): Promise<AuthUserSnapshot | null> {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    select: {
      id: true,
      name: true,
      email: true,
      avatar: true, // ★ 追加
      role: {
        select: { code: true, priority: true },
      },
    },
  });

  if (!user || !user.role) return null;

  return {
    userId: user.id,
    name: user.name,
    email: user.email,
    avatarUrl: user.avatar ? `/avatar/${user.id}` : null, // ★ DB由来に変更
    roleCode: user.role.code,
    rolePriority: user.role.priority,
  };
}

この修正により、ログイン後の useAuth().user.avatarUrl がモック値ではなく、DBに保存されたアバター画像のURLを参照するようになります。以降の UI 実装では、この値をそのまま使えるようになります。

3. 画像アップロード処理（Server Action）

この章では、Server Action を用いてアバター画像をアップロードし、サーバに保存して User.avatar を更新する一連の処理を実装します。API Route は作らず、フォーム送信→サーバ側検証→ファイル保存→DB更新までを 1アクションで完結 させます。

フォームからの送信とクライアント側バリデーション

プロフィール編集フォームから、name と avatarFile（任意）を送信します。クライアントでは既に profileUpdateSchema により 拡張子・容量・推奨ピクセル をチェック済みですが、改ざん防止のためサーバ側でも必ず再検証 します。

txt

[ProfileForm]
  ├─ zodで拡張子/容量チェック（UI）
  └─ formDataで送信（name, avatarFile?）
         ↓
[Server Action]
  ├─ zod & MIME再検証（サーバ）
  ├─ UUID生成 & /var/www/private/avatars/ へ保存
  ├─ 旧ファイルがあれば削除
  └─ prisma.user.update({ avatar: "<uuid>.<ext>" })

サーバ側バリデーション（MIME/容量/拡張子）

クライアント側の zod に加えて、サーバ側では MIME（Content-Type）と拡張子 をチェックします。
最小構成では File.type を参照し、さらに シグネチャ（magic bytes）簡易判定 を行うことで、ヘッダ偽装のリスクを抑えます（PNG/JPEG/WebP/GIF に対応）。

検証ルール一覧（サーバ側）

ルール	内容
容量	`<= MAX_IMAGE_MB * 1024 * 1024`
許可MIME	`image/png`, `image/jpeg`, `image/webp`, `image/gif`
拡張子	`.png`, `.jpg
シグネチャ	代表的な先頭バイト列で簡易判定（PNG/JPEG/WebP/GIFに対応）
保存ファイル名	`crypto.randomUUID() + "." + ext`
保存ディレクトリ	`/var/www/private/avatars/`（Nginx直公開なし・Next.js経由で配信）

fs保存（UUID生成・旧ファイル削除・User.avatar更新）

保存先は /var/www/private/avatars/。ファイル名は UUID + 拡張子 とし、既存アバターが設定済みの場合は 新規保存成功後に旧ファイルを削除 します。
DB には ファイル名のみ （例：550e84...-440000.png）を保存します。

// src/app/_actions/profile-avatar.ts
"use server";

import { prisma } from "@/lib/database";
import { randomUUID } from "crypto";
import { writeFile, unlink, mkdir } from "node:fs/promises";
import { access, constants } from "node:fs";
import { join } from "node:path";
import { lookupSessionFromCookie } from "@/lib/auth/session";
import { profileUpdateSchema, MAX_IMAGE_MB } from "@/lib/users/schema";

const AVATAR_DIR =
  process.env.AVATAR_DIR && process.env.AVATAR_DIR.trim() !== ""
    ? process.env.AVATAR_DIR
    : "/var/www/private/avatars";

type ActionResult =
  | { ok: true }
  | { ok: false; fieldErrors?: Record<string, string>; message?: string };

function getExtFromMime(mime: string): string | null {
  switch (mime) {
    case "image/png":
      return "png";
    case "image/jpeg":
      return "jpg";
    case "image/webp":
      return "webp";
    case "image/gif":
      return "gif";
    default:
      return null;
  }
}

// 簡易シグネチャ検証（magic bytes）: PNG/JPEG/WebP/GIF
function looksValidBySignature(buf: Buffer, mime: string): boolean {
  if (mime === "image/png") {
    // 89 50 4E 47 0D 0A 1A 0A
    return (
      buf.length > 8 &&
      buf[0] === 0x89 &&
      buf[1] === 0x50 &&
      buf[2] === 0x4e &&
      buf[3] === 0x47
    );
  }
  if (mime === "image/jpeg") {
    // FF D8 ... FF D9
    return buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8;
  }
  if (mime === "image/webp") {
    // "RIFF" .... "WEBP"
    return (
      buf.length > 12 &&
      buf.subarray(0, 4).toString() === "RIFF" &&
      buf.subarray(8, 12).toString() === "WEBP"
    );
  }
  if (mime === "image/gif") {
    // "GIF8"
    return buf.length > 4 && buf.subarray(0, 4).toString() === "GIF8";
  }
  return false;
}

async function ensureDir(dir: string) {
  await mkdir(dir, { recursive: true });
}

async function fileExists(path: string): Promise<boolean> {
  return new Promise((resolve) => {
    access(path, constants.F_OK, (err) => resolve(!err));
  });
}

/**
 * プロフィール更新（氏名＋アバター画像）
 * - APIは使わずServer Actionのみ
 * - 画像はUUID名で保存し、User.avatarに「ファイル名」を保存
 */
export async function updateProfileAction(
  formData: FormData,
): Promise<ActionResult> {
  // 1) 認証
  const session = await lookupSessionFromCookie();
  if (!session.ok) return { ok: false, message: "認証が必要です" };

  // 2) クライアント側と同様のzodスキーマで name / avatarFile を検証（UIの改ざん対策）
  const name = String(formData.get("name") ?? "");
  const avatarFile = formData.get("avatarFile");
  const input = {
    name,
    avatarFile: avatarFile instanceof File ? avatarFile : undefined,
  };

  const parsed = await (async () => {
    // profileUpdateSchemaは File | undefined を許容
    const r = profileUpdateSchema.safeParse(input);
    return r;
  })();

  if (!parsed.success) {
    const fieldErrors: Record<string, string> = {};
    for (const issue of parsed.error.issues) {
      const key = issue.path[0]?.toString() || "form";
      fieldErrors[key] = issue.message;
    }
    return { ok: false, fieldErrors };
  }

  // 3) アバターがある場合はサーバ側でもMIME/容量/シグネチャを検証して保存
  let newAvatarFileName: string | null = null;
  let oldAvatarFileName: string | null = null;

  if (parsed.data.avatarFile) {
    const f = parsed.data.avatarFile;
    const mime = f.type;
    const ext = getExtFromMime(mime);
    if (!ext) {
      return {
        ok: false,
        fieldErrors: { avatarFile: "許可されていない画像形式です" },
      };
    }

    const bytes = await f.arrayBuffer();
    const buf = Buffer.from(bytes);

    // 容量の再チェック（サーバ側）
    if (buf.byteLength > MAX_IMAGE_MB * 1024 * 1024) {
      return {
        ok: false,
        fieldErrors: {
          avatarFile: `画像サイズは ${MAX_IMAGE_MB}MB 以下にしてください`,
        },
      };
    }

    if (!looksValidBySignature(buf, mime)) {
      return {
        ok: false,
        fieldErrors: { avatarFile: "画像ファイルの形式を確認できませんでした" },
      };
    }

    // 4) 保存（UUID + 拡張子）
    await ensureDir(AVATAR_DIR);
    const uuid = randomUUID();
    const fileName = `${uuid}.${ext}`;
    const absPath = join(AVATAR_DIR, fileName);
    await writeFile(absPath, buf, { flag: "wx" }); // 上書き防止

    newAvatarFileName = fileName;
  }

  // 5) DB更新（トランザクション）
  await prisma.$transaction(async (tx) => {
    // 旧ファイル名の取得（新規保存があるときのみ）
    if (newAvatarFileName) {
      const current = await tx.user.findUnique({
        where: { id: session.userId },
        select: { avatar: true },
      });
      oldAvatarFileName = current?.avatar ?? null;
    }

    await tx.user.update({
      where: { id: session.userId },
      data: {
        name: parsed.data.name,
        ...(newAvatarFileName ? { avatar: newAvatarFileName } : {}),
      },
    });
  });

  // 6) 旧ファイルの削除（新ファイルのDB反映が済んでから）
  if (oldAvatarFileName) {
    const oldPath = join(AVATAR_DIR, oldAvatarFileName);
    if (await fileExists(oldPath)) {
      // エラーは握りつぶしてOK（ログへ）
      await unlink(oldPath).catch(() => {});
    }
  }

  return { ok: true };
}

認証: lookupSessionFromCookie() でCookie→JWT→Sessionを検証し、本人のみ更新を許可します。
入力検証: UIと同じ profileUpdateSchema をサーバ側でも適用。さらにMIME・シグネチャで偽装を抑止します。
保存: UUID + 拡張子 のファイル名で /var/www/private/avatars/ に保存（flag: "wx" で衝突回避）。
DB更新: 成功後に User.avatar を更新。前のファイル名はトランザクション外で削除します（整合性優先）。
戻り値: UI側は { ok: true } を受けて useAuth().setUser() を呼ぶことでヘッダのアバターを即時反映（5章で実装）。

環境変数の設定

ローカル環境と本番環境のディレクトリを環境変数で設定しておきます。

env

// .env.local
AVATAR_DIR=./private/avatars

env

// .env
AVATAR_DIR=/var/www/private/avatars

それぞれ、設定したディレクトリを作成しておきます。本番サーバの/var/www/private/avatars/ は Next.js（Nodeプロセス）から書き込み可能 にしておきます（例：chown node:node / chmod 750）。アプリをPM2で起動している場合、pm2 listで起動ユーザを調べて、ディレクトリの所有者にします。

運用メモ（権限・パーミッション）

Nginx などのWebサーバからは 直接配信しない 設定にします（ドキュメントルート外・locationで拒否）。
マイグレーションは開発で migrate dev、本番では migrate deploy を推奨（2章の注意書き参照）。

4. アバター配信ルート（非API）

この章では、APIを作らずに Next.js の Route Handler でアバター画像を配信する仕組みを実装します。画像は /var/www/private/avatars/ に保管され、直リンクでは参照できず 、必ずサーバ側の認証・認可を通ってから配信されます。

配信の方針（同一テナント内の認証閲覧を許可）

チャットやメンション一覧で他者のアバター表示が必要なため、配信ルートは 認証必須 のうえで 同一テナント（例：Department 単位）内のユーザーなら閲覧を許可します。
URLは /avatar/[userId] で、未認証は 401、テナント外は 403 を返し、直リンクでの一般公開は行いません。

txt

認可ルール v1（最小構成）

| 条件                          | 結果   |
|-------------------------------|--------|
| 未認証                        | 401    |
| 認証済み & 同一Department     | 200    |
| 認証済み & 異なるDepartment   | 403    |
| 対象ユーザー/ファイル不在     | 404    |

Route Handler の実装（同一Department内の閲覧許可）

session.userId の所属と、params.userId の所属を突き合わせ、同一 departmentId のときだけ画像を返します。
将来的に「Account単位で可」「ROLE=ADMINは跨ぎ可」などへ拡張する余地を残しつつ、まずは最小ルールで運用します。

// src/app/(protected)/avatar/[userId]/route.ts
import { prisma } from "@/lib/database";
import { lookupSessionFromCookie } from "@/lib/auth/session";
import { readFile } from "node:fs/promises";
import { join } from "node:path";

const AVATAR_DIR =
  process.env.AVATAR_DIR && process.env.AVATAR_DIR.trim() !== ""
    ? process.env.AVATAR_DIR
    : "/var/www/private/avatars";

// 画像シグネチャでMIME判定（簡易）
function detectMime(buf: Buffer): string | null {
  if (
    buf.length > 8 &&
    buf[0] === 0x89 &&
    buf[1] === 0x50 &&
    buf[2] === 0x4e &&
    buf[3] === 0x47
  )
    return "image/png";
  if (buf.length > 2 && buf[0] === 0xff && buf[1] === 0xd8) return "image/jpeg";
  if (
    buf.length > 12 &&
    buf.subarray(0, 4).toString() === "RIFF" &&
    buf.subarray(8, 12).toString() === "WEBP"
  )
    return "image/webp";
  if (buf.length > 4 && buf.subarray(0, 4).toString() === "GIF8")
    return "image/gif";
  return null;
}

export async function GET(
  _req: Request,
  ctx: { params: Promise<{ userId: string }> }, // ★ 変更：Promise を受ける
) {
  // 1) 認証
  const session = await lookupSessionFromCookie();
  if (!session.ok) return new Response("Unauthorized", { status: 401 });

  // 2) 動的パラメータを await で取得
  const { userId: targetUserId } = await ctx.params; // ★ 変更：await

  // 3) ビューア&ターゲットの所属を取得（同一Departmentのみ許可）
  const [viewer, target] = await Promise.all([
    prisma.user.findUnique({
      where: { id: session.userId },
      select: { departmentId: true, isActive: true },
    }),
    prisma.user.findUnique({
      where: { id: targetUserId },
      select: { departmentId: true, isActive: true, avatar: true },
    }),
  ]);

  if (!viewer?.isActive) return new Response("Forbidden", { status: 403 });
  if (!target?.isActive) return new Response("Not Found", { status: 404 }); // 秘匿

  // 4) 認可：同一Departmentのみ
  if (viewer.departmentId !== target.departmentId) {
    return new Response("Forbidden", { status: 403 });
  }

  // 5) ファイル解決
  const fileName = target.avatar;
  if (!fileName) return new Response("Not Found", { status: 404 });

  const absPath = join(AVATAR_DIR, fileName);
  let buf: Buffer;
  try {
    buf = await readFile(absPath);
  } catch {
    return new Response("Not Found", { status: 404 });
  }

  // 6) Content-Type
  const mime = detectMime(buf) ?? "application/octet-stream";

  // 7) private 配信（キャッシュ不可）
  const body = new Uint8Array(buf); // ← Buffer を Web 互換へ
  return new Response(body, {
    status: 200,
    headers: {
      "Content-Type": mime,
      "Content-Length": String(body.byteLength),
      "Cache-Control": "private, no-store",
      "Content-Disposition": "inline",
    },
  });
}

同一テナント（Department）判定で「社内の人には見える」を満たしつつ、直リンク/匿名アクセスは防止。
ターゲットが無効化されている場合は 404 を返し、存在を秘匿（ユーザー列挙対策）。
画像自体は 拡張子無しのUUID 名で保存し、配信時にmagic bytesで Content-Type を決定。
キャッシュは private, no-store。チャット等の即時反映を優先し、ブラウザ/中間キャッシュの保持を避けます。

補足：Server Actions / Route Handlers / API Routes の比較
App Router 時代の Next.js では、サーバ処理をどこに実装するか を理解しておくことが重要です。ここでは「Server Actions」「Route Handlers」「API Routes」を比較して整理します。

項目	Server Actions	Route Handlers	API Routes (旧)
配置場所	`app/.../page.tsx` 内や `app/_actions/*.ts`	`app/.../route.ts`	`pages/api/*.ts`
呼び出し方	`<form action={...}>` や `useTransition` から直呼び出し	fetch や URL アクセスで叩く	fetch や URL アクセスで叩く
URL の有無	持たない（内部的に Next.js が扱う）	持つ（`/avatar/[userId]` など直接アクセス可能）	持つ（`/api/...` プレフィックス付き）
主な用途	フォーム送信、DB更新、認可チェックなど	画像配信、Webhook受信、外部公開エンドポイント	Pages Router 時代のAPI実装
利用できるAPI	直接 DB や Server API にアクセス	Web標準の `Request` / `Response`	Node/Express風の `req` / `res`
認証・認可の必須度	ユーザー操作起点なので漏洩しにくい	URL直叩き可能なのでガード必須	URL直叩き可能なのでガード必須
App Router での推奨度	✅ 推奨	✅ 推奨	⚠️ Pages Router専用（レガシー）

（必要に応じて）認可スコープの拡張案

将来の要件に合わせて、以下のように1行ずつ拡張できます。

要件	認可条件の例（書き換え先）
Account単位で可視（部署またぎ）	`viewer.accountId === target.accountId`（JOINで取得）
管理者は全ユーザー閲覧可	`if (viewer.role.priority >= 100) allow`
招待制のルーム単位で可視	ルーム参加テーブルをJOINして `exists` チェック

本記事では Department一致 を最小ルールとして先に進みます。

middleware.tsへの追加

middleware.tsへも/avatarを追加します。これで、認証前の段階でも有効トークンの存在チェックで弾けるようになります。

// middleware.ts（抜粋）
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { verifySessionJwt } from "@/lib/auth/jwt";

const LOGIN_PATH = "/";

// 実際の公開パス（(protected)配下の各ルートのパスを列挙）
const PROTECTED_PATHS = [
  "/changelog",
  "/dashboard",
  "/masters",
  "/tutorial",
  "/users",
  "/profile",
  "/avatar", //追加
];
// 実際の公開パス（(protected)配下の各ルートのパスを列挙）
const PROTECTED_PATHS = [
  "/changelog",
  "/dashboard",
  "/masters",
  "/tutorial",
  "/users",
  "/profile",
  "/avatar", //追加
];

// ── 省略

export const config = {
  matcher: [
    "/changelog/:path*",
    "/dashboard/:path*",
    "/masters/:path*",
    "/tutorial/:path*",
    "/users/:path*",
    "/profile/:path*",
    "/avatar/:path*", //追加
  ],
};

5. フロント実装：フォーム送信と即時反映

この章では、Server Action での保存（3章）・Route Handlerでの配信（4章） を受けて、プロフィール画面からアバターをアップロードし、保存直後にヘッダのアバターも即時に更新される一連の UI を実装します。

ポイントは次の3つです。

フォームから updateProfileAction を呼び出す（サーバで保存 & User.avatar 更新）
保存直後に 最新のユーザースナップショット を Server Action で再取得して AuthContext に反映
反映後、ヘッダ（<NavUser />）のアバターが即座に入れ替わる（ページ遷移なし）

txt

# 構成とデータフロー（5章の最小構成）

[ProfileForm] --(FormData: name, avatarFile)--> [updateProfileAction] --(保存OK)-->
         --(refreshAuthSnapshotAction)--> { user: AuthUserSnapshot } --> [AuthContext.setUser()]
                                                              |
                                                              v
                                                     <NavUser /> の表示更新

UIからサーバまでの流れ

ここで扱う主要な部品と役割を表にまとめます。

レイヤ	ファイル/関数	役割
Server Action	`updateProfileAction`（3章実装済み）	画像の検証・保存、`User.avatar` の更新
Server Action（新規）	`refreshAuthSnapshotAction`（本章で追加）	最新の `AuthUserSnapshot` を取得して返却
Route Handler	`/avatar/[userId]`（4章実装済み）	認証・認可を通じて画像バイトを返却
Context	`AuthContext.setUser()`	アプリ全体にユーザー情報を即時配信
Client	`(protected)/profile/client.tsx`	フォーム送信・トースト・スナップショット再取得・`setUser` 呼び出し

補足（キャッシュ更新）
/avatar/[userId] は Cache-Control: private, no-store を返すため、通常は再読み込みで十分です。
ただし、同一タブで連続更新の即時反映をより確実にするため、クライアント側で取得直後のみ ?ts=... のような一時的なクエリを付与して ワンショットでキャッシュバイパス するのが実務的です（本章の実装に含めます）。

スナップショット再取得の Server Action を追加

アバター保存直後に “最新のユーザー情報” をクライアントへ返すため、極小の Server Action を用意します。
現行ポリシーどおり APIは作らず、Server Action のみで完結させます。

// src/app/_actions/auth-refresh.ts
"use server";

import { lookupSessionFromCookie } from "@/lib/auth/session";
import { getUserSnapshot } from "@/lib/auth/user-snapshot";
import type { AuthUserSnapshot } from "@/lib/auth/types";

export type RefreshResult =
  | { ok: true; user: AuthUserSnapshot }
  | { ok: false; message: string };

export async function refreshAuthSnapshotAction(): Promise<RefreshResult> {
  const session = await lookupSessionFromCookie();
  if (!session.ok) return { ok: false, message: "認証が必要です" };

  const user = await getUserSnapshot(session.userId);
  if (!user) return { ok: false, message: "ユーザー情報の取得に失敗しました" };

  return { ok: true, user };
}

上記は、現在のセッションの userId を基に getUserSnapshot() を呼び、Context 用の軽量データ（AuthUserSnapshot）を返すだけの Server Action です。
UI はこれを呼んで setUser() に渡すことで、ヘッダのアバターや氏名を即時に置き換えられます。

クライアント：プロフィール画面の送信フロー

本節では src/app/(protected)/profile/client.tsx を AuthContext（useAuth()）を唯一の情報源 に切り替え、
アップロード完了後は Server Action で最新スナップショットを再取得 → setUser() で即時反映 する形に統一します。

主な変更点は次のとおりです。

変更点	内容	ねらい
モック依存の排除	`mockUser` の import を削除	実データ（Context）に一本化
初期値の出所	`useAuth().user` から `name / email / roleCode / avatarUrl` を組み立て	表示と更新の一貫性
送信処理	`updateProfileAction()` へ `FormData` で送信	APIを使わずServer Actionで一気通貫
反映処理	`refreshAuthSnapshotAction()` で最新の `AuthUserSnapshot` を取得 → `setUser()`	ヘッダのアバター等を即時反映
キャッシュ回避	`avatarUrl?ts=<now>` を一時付与	ブラウザのキャッシュ無効化
UI配線	`ProfileForm` の `onSubmit` に実処理を渡す	これまでのプレースホルダーを置換

補足：ProfileForm 側は、onSubmit(values) を呼ぶだけでOK（サーバ通信は ProfileClient に集約）です。

tsx

eRouter } from "next/navigation";
import { toast } from "sonner";

import ProfileForm from "@/components/profile/profile-form";
//import { mockUser } from "@/lib/sidebar/mock-user"; ←削除
import type { ProfileUpdateValues } from "@/lib/users/schema";
import { useAuth } from "@/lib/auth/context";
// 3章で作成済みの Server Action
import { updateProfileAction } from "@/app/_actions/profile-avatar";
// 本章で追加した“最新スナップショット取得”の Server Action
import { refreshAuthSnapshotAction } from "@/app/_actions/auth-refresh";

export default function ProfileClient() {
  const router = useRouter();
  const [pending, startTransition] = useTransition();

  const { user, ready, setUser } = useAuth();

  // AuthContext が未初期化の瞬間は描画を保留
  if (!ready) return null;

  // middleware / page.tsx 側で未ログインはリダイレクト済み想定
  if (!user) return null;

  const initial = {
    name: user.name,
    email: user.email,
    roleCode: user.roleCode,
    currentAvatarUrl: user.avatarUrl ?? undefined,
  } as const;

  const handleSubmit = (values: ProfileUpdateValues) => {
    if (pending) return;

    startTransition(async () => {
      try {
        // 1) Server Action へ送信
        const fd = new FormData();
        fd.set("name", values.name);
        if (values.avatarFile) fd.set("avatarFile", values.avatarFile);

        const res = await updateProfileAction(fd);
        if (!res.ok) {
          toast.error(res.message ?? "プロフィールの更新に失敗しました");
          return;
        }

        // 2) 最新スナップショットを取得 → Contextへ即時反映
        const snap = await refreshAuthSnapshotAction();
        if (snap.ok) {
          // ブラウザキャッシュを避けるため一時的に ts を付与
          const ts = Date.now();
          const updated = {
            ...snap.user,
            avatarUrl:
              snap.user.avatarUrl != null
                ? `${snap.user.avatarUrl}?ts=${ts}`
                : null,
          };
          setUser(updated);
        }

        toast.success("プロフィールを更新しました", {
          description: values.avatarFile ? "画像も更新しました" : undefined,
          duration: 3000,
        });
      } catch (e) {
        console.error(e);
        toast.error(
          "予期せぬエラーが発生しました。時間をおいて再試行してください。",
        );
      }
    });
  };

  return (
    <ProfileForm
      initial={initial}
      onSubmit={handleSubmit}
      onCancel={() => history.back()}
      onNavigateEmail={() => router.push("/profile/email")}
      onNavigatePassword={() => router.push("/profile/password")}
    />
  );
}

コード解説

初期値の一本化
initial は useAuth().user からのみ組み立てます。これで 表示（フォーム）とヘッダのユーザ情報が常に同一ソース になります。
送信（updateProfileAction）
FormData で name と avatarFile（任意）を送り、サーバ側で ファイル保存 → User.avatar 更新 を完了させます（APIは使いません）。
反映（refreshAuthSnapshotAction）
DBが更新されたら直ちに 最新スナップショットを取得して setUser()。サイドバーのアバターや NavUser の表示が即座に切り替わります。
なお、ブラウザ画像キャッシュを外すため ?ts= を一時付与しています（FCP重視。後段で ETag 運用に発展可）。
ユーザ体験
成功時は「氏名のみ」「氏名＋画像」のいずれにも対応したトーストを表示。エラー時は適切なメッセージを提示します。

`profile-form.tsx`の若干の変更

アバター画像について、next/image の最適化（Image Optimization API）が入ると、/_next/image?... 経由で再リクエストが走り、その際に Cookie が外れる or 認証が二重に必要になります。アバター画像自体はサイズが小さいものなので、unoptimizedオプションを指定して、Next.js 独自の Image Optimization を避け、直接 Route Handler のレスポンスを利用します。

tsx

// src/components/profile/profile-form.tsx（一部抜粋）

// ──省略

            <div className="size-16 min-w-16 overflow-hidden rounded-full border">
              {previewUrl || currentAvatarUrl ? (
                <Image
                  src={previewUrl ?? currentAvatarUrl!}
                  alt="アバターのプレビュー"
                  width={64}
                  height={64}
                  className="h-full w-full object-cover"
                  unoptimized  // ★追加
                />
              ) : (
                <div className="text-muted-foreground flex h-full w-full items-center justify-center text-xs">
                  No Image
                </div>
              )}
            </div>

認証が前提 の画像については、unoptimized を標準設定にします。

ヘッダーのアバターは自動で切り替わる

<NavUser /> は useAuth() の user?.avatarUrl を参照して描画しており、5章の setUser(updated) により 即時でヘッダーの画像が切り替わります。
NavUser 側のコード変更は不要です（2章・4章の実装に追随して自動反映されます）。

失敗時の挙動とUXメモ

保存～即時反映の間で起きうる失敗を整理し、UIのふるまいを決めておきます。

失敗ポイント	想定原因	UI のふるまい（推奨）
送信前のクライアント検証	拡張子・容量・必須	`ProfileForm` の `FormMessage` に表示（既実装）
Server Action の入力検証	MIME不正・シグネチャ不一致・容量超過	`res.fieldErrors.avatarFile` を `FormMessage` に表示
ファイル保存	権限・ディレクトリ未作成	`res.message` をトースト。権限/パスは 2章・3章の手順で確認
DB更新	トランザクション失敗	トースト＋コンソールログ
スナップショット再取得	セッション切れ・ネットワーク	成功トーストは出すが `setUser` はスキップ（再読込で復旧）
反映直後に画像が古いまま	ブラウザの一時キャッシュ	`?ts=` 付与で解消（本章の実装）

運用ワンポイント
本番では PM2 の実行ユーザー（例：node）に /var/www/private/avatars の書込権限があることを必ず確認してください。
Nginx からはそのディレクトリを配信させず、Next.js の Route Handler 経由のみ にします（4章参照）。

動作確認チェックリスト

画像未選択で「氏名のみ」更新 → ヘッダの氏名が即時反映される
画像を選択して更新 → ヘッダのアバターがその場で差し替わる
許可されない拡張子/容量超過 → FormMessage にエラー表示
別ユーザーでログインして /avatar/[他人のuserId] へ直アクセス → 403/404 になる
ログアウト状態で /avatar/[userId] へアクセス → 401（または middleware によるリダイレクト）
本番サーバで PM2 実行ユーザーが /var/www/private/avatars に書ける

— 以上で、フォーム送信からサーバ保存・配信・アプリ全体の即時反映までの UI 実装が完了です。次章では、テストケースと運用のベストプラクティス（バックアップ・削除ポリシーなど）を整理します。

6. まとめと次回予告

ここまでで、アバター画像の 保存・配信・即時反映 までの一連の仕組みを整備しました。
ログイン済みユーザーのプロフィール編集画面からアップロードし、認証・認可を通して安全に表示されるまでを、Server Action と Route Handler だけで実現できた点が大きなポイントです。

今回の実装を整理すると、以下のようになります。

txt

[ProfileForm] --(FormData)--> [updateProfileAction] --(保存・DB更新)-->
         --(refreshAuthSnapshotAction)--> [AuthContext.setUser()]
                                |
                                v
                        <NavUser /> 即時反映

今回の実装で得られたこと

項目	内容
Prismaスキーマ	`User.avatar` カラムを追加
保存処理	Server Action で UUID+拡張子形式で保存
配信処理	Route Handler 経由で認証必須・同一Departmentのみ表示
即時反映	Server Action で最新スナップショットを取得し、`AuthContext` を更新
UI側	`setUser()` 呼び出しによりヘッダのアバターが即座に切り替わる

今回のアプローチにより、直リンク不可・セキュアな配信 が可能になり、かつ ユーザー体験の即時性 も確保できました。

次回予告

次回はアバター以外のプロフィール関連、すなわち 氏名・メール・パスワードといった基本情報のDB連携 を扱います。
具体的には以下のような機能を中心に進めていく予定です。

アバター画像の削除
プロフィール編集フォームからの 氏名変更
メールアドレス変更フロー（認証付きでの更新）
パスワード変更フォーム とサーバ側バリデーション
変更後の即時反映と AuthContext 更新

アバター画像で実現した「Server Actionによる保存」と「スナップショット再取得」の仕組みを横展開し、プロフィール全体の編集を安全に完結できるようにします。

これにより、管理画面フォーマットのユーザー管理機能がさらに実務的な形へと近づきます。

参考文献

本記事の執筆にあたり、Next.js の公式ドキュメントや関連資料を参照しました。
特に App Router 時代における Server Actions / Route Handlers の扱いと、セキュリティ設計に関する情報は実装方針を定める上で重要です。

Next.js Documentation – Route Handlers and Middleware
App Router における Route Handler の基本と、Middleware との使い分けについて解説。
Next.js Documentation – Server Actions
フォーム送信やデータ更新を API を介さず実現する方法をまとめた公式ガイド。
Prisma Documentation – Relations and Data Modeling
Prisma スキーマの設計と、User モデルへのフィールド追加に関するリファレンス。
MDN Web Docs – MIME types (IANA media types)
アバター画像の MIME 判定や拡張子管理の基礎知識。
MDN Web Docs – Cache-Control
認証付き画像配信におけるキャッシュ制御（private, no-store）の参考。
Node.js Documentation – fs/promises
ファイルの保存・削除処理に利用する fs/promises API のリファレンス。

この記事の執筆・編集担当

松本孝太郎

DELOGs編集部/中年新米プログラマー

ここ数年はReact&MUIのフロントエンドエンジニアって感じでしたが、Next.jsを学んで少しずつできることが広がりつつあります。その実践記録をできるだけ共有していければと思っています。

ログイン成功直後に取得したユーザー情報をAuthProvider（Client Context）でアプリ全体に配布

2025/9/12公開

[管理画面フォーマット開発編 #3] AuthProviderでログイン済みユーザー情報を全体共有のイメージ

[管理画面フォーマット開発編 #2] JWT +Cookie＋middlewareで実装するログイン機能

httpOnly Cookie と middleware を組み合わせ、JWTはjtiのみを運ぶ“鍵”として使用。法人ユースに耐える堅牢なログインを実装