feat: Externalize runtime data, including SQLite and caches, to a configurable directory mounted via Docker volumes.

.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.

.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/
+.npm-cache/

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

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

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}"