diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..4af91bb
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,29 @@
+# =====================================================================
+# 实验室预约与资源管理平台 - Docker Compose 环境变量示例
+#
+# 使用方式：
+#   cp .env.example .env      # 复制后按需修改，docker compose 会自动读取 .env
+#   docker compose up -d --build
+#
+# 注意：.env 已在 .gitignore 中忽略，请勿把真实密码/密钥提交到仓库。
+# =====================================================================
+
+# ---------- 数据库（MariaDB） ----------
+# 首次创建数据卷时生效；修改后如需重建，先执行 docker compose down -v
+DB_NAME=lab
+DB_USER=lab
+DB_PASSWORD=lab123456
+DB_ROOT_PASSWORD=root123456
+
+# ---------- 后端 ----------
+# JWT 签名密钥，长度必须 >= 32 字节；生产环境请替换为随机值
+# 生成示例：openssl rand -base64 48
+LAB_JWT_SECRET=lab-reservation-docker-secret-key-change-me-2026
+# JVM 参数（容器内存较小可下调 -Xmx）
+JAVA_OPTS=-Xms256m -Xmx512m
+
+# ---------- 端口映射（宿主机端口） ----------
+# 前端 Nginx 端口，若本机 80 被占用可改为 8088
+WEB_PORT=80
+# 后端直连端口（调试用，前端经 Nginx 代理访问后端）
+BACKEND_PORT=8080
diff --git a/.gitignore b/.gitignore
index 07ecd4f..817a986 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,3 +38,7 @@ frontend/.vite/
 
 ### H2 本地数据库文件 ###
 data/
+
+### 本地环境变量（保留示例文件） ###
+.env
+!.env.example
diff --git a/README.md b/README.md
index 2b1fcd1..e85b638 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ pnpm build      # 生产构建（vue-tsc 类型检查 + vite build）
 ### 3. Docker 一键部署（推荐用于演示/验收）
 
 ```bash
+cp .env.example .env             # 可选：按需修改端口/密码/JWT 密钥
 docker compose up -d --build     # 构建并启动 mariadb + backend + frontend
 # 前端：http://localhost         （Nginx 托管静态资源并反代 /api）
 # 后端：http://localhost:8080
@@ -56,8 +57,8 @@ docker compose down -v           # 停止并清空数据库（下次启动重建
 
 - 编排：`mariadb:11.4`（数据持久化到命名卷）+ 后端多阶段构建镜像（JRE 21，非 root 运行）+ Nginx 前端镜像
 - 三个服务均配置健康检查，后端与前端会等待上游就绪后再启动
-- 可用环境变量覆盖：`WEB_PORT`（默认 80）、`BACKEND_PORT`（默认 8080）、
-  `DB_NAME` / `DB_USER` / `DB_PASSWORD` / `DB_ROOT_PASSWORD`、`LAB_JWT_SECRET`
+- 可用环境变量（见 `.env.example`）：`WEB_PORT`（默认 80）、`BACKEND_PORT`（默认 8080）、
+  `DB_NAME` / `DB_USER` / `DB_PASSWORD` / `DB_ROOT_PASSWORD`、`LAB_JWT_SECRET`、`JAVA_OPTS`
 
 ### 4. 演示账号
 
@@ -138,6 +139,7 @@ mvn verify        # 运行全部测试并执行 JaCoCo 覆盖率门禁
 │   └── nginx.conf
 ├── Dockerfile           # 后端多阶段构建镜像
 ├── docker-compose.yml   # mariadb + backend + frontend 一键编排
+├── .env.example         # 部署环境变量示例（复制为 .env 使用）
 └── docs/design.md       # 需求分析与详细设计
 ```
 
diff --git a/docker-compose.yml b/docker-compose.yml
index e81da32..b4d1311 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -63,7 +63,7 @@ services:
       # 生产部署请务必覆盖为随机密钥（长度 >= 32 字节）
       LAB_JWT_SECRET: ${LAB_JWT_SECRET:-lab-reservation-docker-secret-key-change-me-2026}
       TZ: Asia/Shanghai
-      JAVA_OPTS: "-Xms256m -Xmx512m"
+      JAVA_OPTS: "${JAVA_OPTS:--Xms256m -Xmx512m}"
     depends_on:
       mariadb:
         condition: service_healthy