diff --git a/.env.example b/.env.example
index 4098463..28016f9 100644
--- a/.env.example
+++ b/.env.example
@@ -6,12 +6,15 @@
 PORT=3000
 
 # PostgreSQL 连接串
-DATABASE_URL=postgres://user:password@localhost:5432/new_api_key_usage
+# 本地开发：与仓库根 docker-compose.yml 配套（宿主端口 5433）
+# 生产：改为实例运营方提供的连接串
+DATABASE_URL=postgres://naku:naku-dev@localhost:5433/naku
 
 # 管理面口令（请求头 X-Manage-Token；见 API 契约 约定 6）
 MANAGE_TOKEN=change-me
 
 # 凭证主密钥（HKDF 派生 hmac / aes 子密钥；丢失 = 全部 key 需重新登记）
+# 生成示例：openssl rand -base64 32
 KEYS_MASTER_KEY=change-me-32-bytes-base64
 
 # 上游 NewAPI 站点地址（同步引擎调用的 BaseURL，不带尾部斜杠）
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..e267037
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,23 @@
+# 本地开发用 PostgreSQL（仅开发；生产用实例运营方的 PG 实例）
+# 起库：docker compose up -d    查看：docker compose logs -f db
+services:
+  db:
+    image: postgres:17-alpine
+    container_name: naku-db
+    environment:
+      POSTGRES_USER: naku
+      POSTGRES_PASSWORD: naku-dev
+      POSTGRES_DB: naku
+    ports:
+      # 宿主端口用 5433，避开本机可能已有的 5432
+      - '5433:5432'
+    volumes:
+      - naku-db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U naku -d naku']
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+volumes:
+  naku-db-data: