diff --git a/.env.example b/.env.example
index 0d53e87..bf7a0be 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,9 @@
 NODE_ENV=development
 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/personal_brand
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=personal_brand
+POSTGRES_PORT=5432
 API_PORT=3001
 ADMIN_PORT=3000
 SESSION_SECRET=replace-with-a-long-random-value
diff --git a/README.md b/README.md
index 9939b83..894f40a 100644
--- a/README.md
+++ b/README.md
@@ -28,3 +28,41 @@ corepack enable
 pnpm install
 pnpm check
 ```
+
+## 本地数据库
+
+在有 Docker 的机器上执行：
+
+```bash
+cp .env.example .env
+docker compose up -d postgres
+docker compose ps
+pnpm db:migrate
+pnpm db:seed
+```
+
+确认数据库健康后，再启动 API：
+
+```bash
+pnpm --filter @personal-brand/api dev
+```
+
+停止数据库但保留数据：
+
+```bash
+docker compose stop postgres
+```
+
+停止并删除容器但保留数据卷：
+
+```bash
+docker compose down
+```
+
+删除容器和本地数据库数据（不可恢复）：
+
+```bash
+docker compose down -v
+```
+
+`DATABASE_URL` 用于宿主机运行 API 时连接 `localhost`。如果以后把 API 也放进 Compose，连接地址应改为服务名 `postgres`，不能继续使用 `localhost`。
diff --git a/apps/api/package.json b/apps/api/package.json
index de1e76c..723e1ef 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -11,6 +11,7 @@
     "start": "node dist/main.js",
     "db:generate": "prisma generate",
     "db:migrate": "prisma migrate dev",
+    "db:migrate:deploy": "prisma migrate deploy",
     "db:seed": "tsx prisma/seed.ts"
   },
   "dependencies": {
diff --git a/docker-compose.yml b/docker-compose.yml
index 71babc7..5d97330 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,15 +1,22 @@
 services:
   postgres:
     image: postgres:16-alpine
+    container_name: personal-brand-postgres
     restart: unless-stopped
     environment:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: personal_brand
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+      POSTGRES_DB: ${POSTGRES_DB:-personal_brand}
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     volumes:
       - personal-brand-postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+      start_period: 5s
 
 volumes:
   personal-brand-postgres: