From fcf071cfaabfde9b647685d79c475e0091a8f116 Mon Sep 17 00:00:00 2001
From: dekun <dekun@local>
Date: Sat, 13 Jun 2026 09:47:57 +0800
Subject: [PATCH] Document env reload and restart steps in DOCKER.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/DOCKER.md | 88 +++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 76 insertions(+), 12 deletions(-)

diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 57552f6..ad0fb5c 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -47,14 +47,88 @@ docker compose build
 docker compose up -d
 ```
 
+## 修改环境变量后重启
+
+环境变量写在项目根目录的 `.env.local` 中，由 `docker-compose.yml` 的 `env_file` 注入容器。**变量在创建容器时读取**，改 env 后必须**重建容器**才会生效。
+
+### 服务器（Docker）
+
+```bash
+cd /opt/zhimingge
+nano .env.local          # 改完保存
+docker compose up -d --force-recreate
+```
+
+确认服务正常：
+
+```bash
+curl http://127.0.0.1:3130/api/health
+docker compose logs -f zhimingge   # 有问题时看日志
+```
+
+> **注意：** `docker compose restart zhimingge` 只是重启旧容器，**不会**重新读取 `.env.local`。改 env 后请用 `--force-recreate`，不要用 `restart`。
+
+改 env **不需要**重新 `build` 镜像；只有**代码变更**时才需要 `git pull` + `docker compose build` + `up -d`。
+
+### 本地开发
+
+```bash
+# 改 .env.local 后，Ctrl+C 停掉 dev 进程，再重新启动
+npm run dev
+```
+
+Next.js 只在启动时读取 env，热更新不会自动加载新变量。
+
+### PM2 部署（旧方式）
+
+若仍使用 PM2 而非 Docker：
+
+```bash
+cd /opt/zhimingge
+nano .env.local
+pm2 restart zhimingge
+```
+
+### 快速对照
+
+| 场景 | 改 env 后怎么做 |
+|------|----------------|
+| Docker 生产 | `docker compose up -d --force-recreate` |
+| 本地 dev | 停掉再 `npm run dev` |
+| PM2 | `pm2 restart zhimingge` |
+
+## 环境变量
+
+通过 `.env.local` 注入容器（见 `docker-compose.yml` 的 `env_file`）：
+
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `OPENAI_API_KEY` | 是 | AI 接口密钥 |
+| `OPENAI_BASE_URL` | 否 | 默认 `https://op.bz121.com/v1` |
+| `OPENAI_MODEL` | 否 | 默认 `huihui_ai/gemma-4-abliterated:e4b` |
+| `AUTH_USERNAME` | 否* | 登录用户名；与下面两项同时配置后启用登录 |
+| `AUTH_PASSWORD` | 否* | 登录密码 |
+| `AUTH_SESSION_SECRET` | 否* | 会话签名密钥，建议 32 位以上随机字符串 |
+| `PORT` | 否 | 容器内 3130 |
+
+\* 三项认证变量**同时**填写时，六爻/八字/综合测算与 AI 解读需登录；任一项留空则关闭登录限制。
+
+验证容器内是否生效（示例）：
+
+```bash
+docker exec zhimingge printenv OPENAI_API_KEY
+docker exec zhimingge printenv AUTH_USERNAME
+```
+
 ## 常用命令
 
 ```bash
 docker compose ps                    # 状态
 docker compose logs -f zhimingge     # 日志
-docker compose restart zhimingge     # 重启
+docker compose restart zhimingge     # 重启容器（不改 env 时用）
+docker compose up -d --force-recreate  # 重建容器（改 .env.local 后用）
 docker compose down                  # 停止并删除容器
-docker compose up -d --build         # 重建并启动
+docker compose up -d --build         # 重建镜像并启动（代码更新后用）
 ```
 
 ## 镜像清理
@@ -153,16 +227,6 @@ docker compose up -d --force-recreate
 curl -s http://127.0.0.1:3130/api/health
 ```
 
-
-通过 `.env.local` 注入容器（见 `docker-compose.yml` 的 `env_file`）：
-
-| 变量 | 必填 | 说明 |
-|------|------|------|
-| `OPENAI_API_KEY` | 是 | AI 接口密钥 |
-| `OPENAI_BASE_URL` | 否 | 默认 `https://op.bz121.com/v1` |
-| `OPENAI_MODEL` | 否 | 默认 `huihui_ai/gemma-4-abliterated:e4b` |
-| `PORT` | 否 | 容器内 3130 |
-
 ## 防火墙
 
 ```bash