From 08217deefb2add5c2a61d51b9f50be053acbeaf5 Mon Sep 17 00:00:00 2001
From: "2569718930@qq.com" <2569718930@qq.com>
Date: Fri, 13 Mar 2026 17:18:06 +0800
Subject: [PATCH] feat: Externalize runtime data, including SQLite and caches,
 to a configurable directory mounted via Docker volumes.

---
 .env.example       |  6 ++++++
 .gitignore         |  5 ++++-
 README.md          | 22 ++++++++++++++++++++++
 README_ZH.md       | 22 ++++++++++++++++++++++
 docker-compose.yml |  9 +++++++--
 5 files changed, 61 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index 42c414d3..f6994cd7 100644
--- a/.env.example
+++ b/.env.example
@@ -26,6 +26,12 @@ HTTP_PROXY=http://127.0.0.1:7890
 LOG_LEVEL=INFO
 ENV=production
 POLYWEATHER_MAP_URL=https://polyweather-pro.vercel.app/
+# Runtime data directory (host path mounted into container at /var/lib/polyweather and /app/data)
+POLYWEATHER_RUNTIME_DATA_DIR=/var/lib/polyweather
+# Recommended: keep SQLite outside repository workspace
+POLYWEATHER_DB_PATH=/var/lib/polyweather/polyweather.db
+# Recommended disk cache/state paths (optional; defaults are still /app/data/*)
+OPEN_METEO_DISK_CACHE_PATH=/var/lib/polyweather/open_meteo_cache.json
 # Unified Auth (Supabase + Google/Email)
 POLYWEATHER_AUTH_ENABLED=false
 # If true: website APIs require login; if false: guest access, login optional.
diff --git a/.gitignore b/.gitignore
index 37c29f3a..335ef1a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,9 @@
 .env
 
 # Data and Logs
+data/*.db
+data/*.db-*
+data/*.db.*
 data/*.json
 data/logs/
 data/historical/
@@ -31,4 +34,4 @@ frontend/node_modules/
 frontend/.next/
 frontend/.vercel/
 
-.npm-cache/
\ No newline at end of file
+.npm-cache/
diff --git a/README.md b/README.md
index 21ccc585..b832e602 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,28 @@ flowchart TD
 docker compose up -d --build
 ```
 
+## Runtime Data (Recommended for VPS)
+
+To avoid `git pull` conflicts and decouple code from runtime state, store SQLite and caches outside the repo:
+
+1. Set in `.env`:
+   - `POLYWEATHER_RUNTIME_DATA_DIR=/var/lib/polyweather`
+   - `POLYWEATHER_DB_PATH=/var/lib/polyweather/polyweather.db`
+2. Ensure host directory exists and has write permission for container user (`1000:1000`):
+
+```bash
+sudo mkdir -p /var/lib/polyweather
+sudo chown -R 1000:1000 /var/lib/polyweather
+sudo chmod 775 /var/lib/polyweather
+```
+
+3. Recreate services:
+
+```bash
+docker compose down
+docker compose up -d --build
+```
+
 ### Frontend (local)
 
 ```bash
diff --git a/README_ZH.md b/README_ZH.md
index f4384028..d8f7ef9c 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -119,6 +119,28 @@ flowchart TD
 docker compose up -d --build
 ```
 
+## 运行数据目录（VPS 推荐）
+
+为避免 `git pull` 被数据库阻塞，并实现代码与运行态数据解耦，建议把 SQLite 和缓存放到仓库外目录：
+
+1. 在 `.env` 设置：
+   - `POLYWEATHER_RUNTIME_DATA_DIR=/var/lib/polyweather`
+   - `POLYWEATHER_DB_PATH=/var/lib/polyweather/polyweather.db`
+2. 确保宿主机目录存在且容器用户（`1000:1000`）可写：
+
+```bash
+sudo mkdir -p /var/lib/polyweather
+sudo chown -R 1000:1000 /var/lib/polyweather
+sudo chmod 775 /var/lib/polyweather
+```
+
+3. 重建服务：
+
+```bash
+docker compose down
+docker compose up -d --build
+```
+
 ### 前端本地运行
 
 ```bash
diff --git a/docker-compose.yml b/docker-compose.yml
index bfc6fdfb..433c82e9 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,7 +6,11 @@ services:
     env_file:
       - .env
     volumes:
-      - ./data:/app/data # 挂载数据目录，确保历史数据持久化
+      # Persist runtime data outside git workspace.
+      # Host path defaults to /var/lib/polyweather and can be overridden by POLYWEATHER_RUNTIME_DATA_DIR.
+      - ${POLYWEATHER_RUNTIME_DATA_DIR:-/var/lib/polyweather}:/var/lib/polyweather
+      # Keep /app/data compatibility for existing cache/state defaults.
+      - ${POLYWEATHER_RUNTIME_DATA_DIR:-/var/lib/polyweather}:/app/data
       - ./bot.log:/app/bot.log # 挂载日志文件
     user: "${UID:-1000}:${GID:-1000}"
 
@@ -18,7 +22,8 @@ services:
     env_file:
       - .env
     volumes:
-      - ./data:/app/data
+      - ${POLYWEATHER_RUNTIME_DATA_DIR:-/var/lib/polyweather}:/var/lib/polyweather
+      - ${POLYWEATHER_RUNTIME_DATA_DIR:-/var/lib/polyweather}:/app/data
     ports:
       - "8000:8000"
     user: "${UID:-1000}:${GID:-1000}"