chore: harden delivery configuration and runbooks

Author: jiwenxu025-boop

.env.example

@@ -0,0 +1,15 @@
+# Do not put real credentials in this file or commit a populated .env file.
+BAZI_PUBLIC=true
+BAZI_AI_ENABLED=true
+BAZI_FUSION_ENGINE=0
+BAZI_LLM_REVIEW=0
+
+# Set these only in the protected production environment.
+DEEPSEEK_API_KEY=
+DEEPSEEK_MODEL=deepseek-chat
+BAZI_ADMIN_KEY=
+
+# Optional service limits.
+BAZI_MAX_AI_STREAMS=3
+BAZI_FUSION_TEMPERATURE=0.3
+BAZI_FUSION_REPAIR=1

.github/workflows/ci.yml

@@ -29,27 +29,6 @@ jobs:
       - name: Install dependencies
         run: |
           pip install -r requirements.txt
-      - name: Import check
-        run: |
-          cd scripts && python -c "
-import sys; sys.path.insert(0, '.')
-from bazi_engine.enums import Tiangan, Dizhi, Wuxing
-from bazi_engine.ten_gods import wuxing_relation, get_ten_god
-from bazi_engine.nayin_chain import find_all_nayin_relations
-from bazi_engine.day_pillar_db import lookup_day_pillar, verify_known_cases
-# Verify day pillar calculation
-assert verify_known_cases(), 'Day pillar verification failed'
-print('All imports OK')
-"
-      - name: Quick integration test
-        run: |
-          cd scripts && python -c "
-import sys; sys.path.insert(0, '.')
-from bazi_engine.chart import build_chart
-c = build_chart('test', '\u7537', 1990, 6, 15, 12)
-d = c.to_dict()
-assert d.get('four_pillars', {}).get('year'), 'Missing year pillar'
-year_pillar = d['four_pillars']['year']
-print(f'Chart built: {year_pillar.get(\"stem\")}{year_pillar.get(\"branch\")}')
-print('Integration test OK')
-"
+          pip install -r requirements-dev.txt
+      - name: Full test suite
+        run: cd scripts && python -m pytest tests/ -q

.github/workflows/test.yml

@@ -1,19 +1,20 @@
-# Bazi Engine — Docker 部署
 FROM python:3.13-slim
 
-WORKDIR /app
-
-# 安装依赖
 COPY requirements.txt /app/requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
 
-# 复制代码
-COPY scripts/ /app/scripts/
-COPY frontend/ /app/frontend/
+RUN addgroup --system app && adduser --system --ingroup app --home /app app
+
+WORKDIR /app/scripts
+
+COPY --chown=app:app scripts/ /app/scripts/
+COPY --chown=app:app frontend/ /app/frontend/
 
 ENV FRONTEND_DIR=/app/frontend
 ENV BAZI_PUBLIC=true
 
 EXPOSE 7860
 
-CMD ["python", "-m", "uvicorn", "scripts.bazi_engine.api:app", "--host", "0.0.0.0", "--port", "7860"]
+USER app
+
+CMD ["python", "-m", "uvicorn", "bazi_engine.api:app", "--host", "0.0.0.0", "--port", "7860"]

Dockerfile

@@ -53,8 +53,11 @@
 
 ```bash
 git clone https://github.com/jiwenxu025-boop/bazi-engine.git
-cd bazi-engine/scripts
-pip install -r requirements.txt
+cd bazi-engine
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# macOS/Linux: source .venv/bin/activate
+python -m pip install -r requirements.txt
 ```
 
 ## 使用
@@ -81,7 +84,8 @@ python -m uvicorn bazi_engine.api:app --host 0.0.0.0 --port 8000
 ### 测试
 
 ```bash
-# 单元测试
+python -m pip install -r requirements-dev.txt
+cd scripts
 python -m pytest tests/ -q
 
 # 校准测试
@@ -171,7 +175,7 @@ bazi-engine/
 3. 添加环境变量：
    ```
    BAZI_PUBLIC=true
-   DEEPSEEK_API_KEY=sk-xxx    # 可选，启用 AI 追问
+   DEEPSEEK_API_KEY=          # 可选，启用 AI 追问，不要提交到仓库
    DEEPSEEK_MODEL=deepseek-chat
    BAZI_LLM_REVIEW=1          # 可选，启用 LLM 推理层
    ```
@@ -181,6 +185,10 @@ bazi-engine/
 
 浏览器打开 `frontend/index.html`，API 地址填写公网 URL 即可远程排盘。
 
+### 生产运维
+
+生产环境变量请从 `.env.example` 创建，并保存在仓库外或受权限保护的 `.env` 中。部署、回滚、备份和公网 HTTP 风险说明见 [docs/operations.md](docs/operations.md)。
+
 ## 免责声明
 
 本引擎仅供传统文化学习与娱乐参考，分析结果不构成任何决策依据。命理学属于传统文化范畴，请理性看待。

README.md

@@ -0,0 +1,30 @@
+# 生产运维
+
+本项目的运行数据位于 `/opt/bazi/data/`。该目录包含反馈、配额和生成指标，必须保留在版本控制之外。
+
+## 首次部署
+
+1. 在服务器创建受限权限的环境文件：`/opt/bazi/.env`，并执行 `chmod 600 /opt/bazi/.env`。
+2. 以 [`.env.example`](../.env.example) 为字段清单填入生产值。不要把密钥写入命令行、仓库或聊天记录。
+3. 确认 `bazi.service` 的 `EnvironmentFile` 指向 `/opt/bazi/.env`，运行用户拥有 `/opt/bazi/data/` 的读写权限。
+4. 启动服务后检查服务器内网和公网的 `/api/health`。健康响应中的 `ai_enabled` 只表示 AI 功能开关，不暴露凭证。
+
+## 常规发布
+
+1. 在本地完成测试、静态检查和提交推送。
+2. 在服务器执行 `git pull --ff-only`，不要删除或重建 `/opt/bazi/data/`。
+3. 重启 `bazi.service`，等待服务就绪后检查 `systemctl is-active bazi.service` 与 `/api/health`。
+4. 对涉及前端的改动，在桌面和移动视口各做一次浏览器验证。
+
+## 回滚
+
+通过 GitHub 对有问题的提交执行 revert，再按常规发布流程部署 `main`。不要在生产机上通过强制重置 Git 历史回滚，以免丢失未同步的运行状态。
+
+## 备份
+
+每日将 `/opt/bazi/data/` 归档到仓库外的受限目录或对象存储，并定期演练还原。备份应加密并设置保留期，因为反馈与运行指标虽然不含报告正文，仍属于运营数据。
+
+## 访问边界
+
+- 管理汇总接口需要 `X-Admin-Key` 或 Bearer 管理密钥；不要为了排查问题临时关闭认证。
+- 当前公网服务仅提供 HTTP。POST 可以避免把出生信息放进 URL，但不能提供传输加密。正式 HTTPS 上线应等待域名备案和证书配置完成。