feat(docker): support Windows and macOS deployment with named volumes

docker/README.md

@@ -22,6 +22,8 @@ This project provides the following docker compose configurations:
 - **docker-compose-self-hosted-ob.yml**  
   Sets up environment for PowerRAG and its dependencies, using self-hosted OceanBase or SeekDB as the database.
 
+All configurations use **Docker named volumes** for data persistence, ensuring cross-platform compatibility across Linux, Windows, and macOS. Configuration files are mounted as read-only from the repository.
+
 The program uses docker-compose.yml by default. You can specify a configuration file using `docker compose -f`. For example, when starting services with a self-hosted database, you can use the following command:
 
 ```shell
@@ -198,6 +200,138 @@ If you already have SSL certificates from another provider:
 
 ## 🔧 Troubleshooting
 
+### Platform-Specific Considerations
+
+PowerRAG's Docker deployment has been designed to work across Linux, Windows, and macOS. The Docker Compose files use **named Docker volumes** for data persistence, which ensures cross-platform compatibility.
+
+#### Windows
+
+When running on Windows, ensure:
+- **Docker Desktop** is installed and running with WSL 2 backend enabled (recommended)
+- If you encounter issues with configuration files, check that configuration files (in `nginx/`, `oceanbase/init.d/`, etc.) use **LF line endings** instead of CRLF:
+  ```bash
+  git config core.autocrlf false
+  git rm --cached -r .
+  git reset --hard
+  ```
+- File paths in volume mounts are handled automatically by Docker Desktop
+
+#### macOS
+
+When running on macOS:
+- **Docker Desktop** is installed and running
+- Set the `MACOS` environment variable in your `.env` file:
+  ```dotenv
+  MACOS=1
+  ```
+- For Apple Silicon (M1/M2/M3), Docker will automatically handle platform emulation
+
+#### Linux
+
+Linux is the primary development platform and should work without additional configuration.
+
+### Volume Management
+
+PowerRAG uses Docker named volumes to store persistent data (logs, database files, history data). These volumes persist across container restarts and updates.
+
+#### Multiple Deployments
+
+Docker Compose automatically prefixes volume names with the project name (from `COMPOSE_PROJECT_NAME` in `.env`, default is `powerrag`). This allows multiple deployments on the same machine without conflicts:
+
+**Example volume naming:**
+- With `COMPOSE_PROJECT_NAME=powerrag`: volumes become `powerrag_powerrag_logs`, `powerrag_oceanbase_data`, etc.
+- With `COMPOSE_PROJECT_NAME=powerrag-dev`: volumes become `powerrag-dev_powerrag_logs`, `powerrag-dev_oceanbase_data`, etc.
+
+**To run multiple deployments:**
+1. Create separate directories for each deployment
+2. In each directory's `.env` file, set a unique `COMPOSE_PROJECT_NAME`:
+   ```dotenv
+   COMPOSE_PROJECT_NAME=powerrag-production
+   # or
+   COMPOSE_PROJECT_NAME=powerrag-dev
+   ```
+3. Each deployment will have its own isolated set of volumes
+
+#### Listing Volumes
+
+To see all PowerRAG-related volumes:
+```bash
+docker volume ls | grep powerrag
+```
+
+#### Backing Up Volumes
+
+Before cleaning up or upgrading, you may want to back up your data:
+
+```bash
+# Back up all PowerRAG volumes
+docker run --rm -v powerrag_powerrag_logs:/data -v $(pwd)/backup:/backup alpine tar czf /backup/powerrag_logs.tar.gz -C /data .
+docker run --rm -v powerrag_oceanbase_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/oceanbase_data.tar.gz -C /data .
+docker run --rm -v powerrag_powerrag_history_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/history_data.tar.gz -C /data .
+```
+
+#### Cleaning Up Volumes
+
+> [!WARNING]
+> Removing volumes will permanently delete all data including logs, database contents, and history. Make sure to back up any important data first.
+
+**To remove all PowerRAG volumes and data:**
+
+```bash
+# Stop and remove all containers
+docker compose down
+
+# Remove all PowerRAG volumes
+docker compose down -v
+
+# Or manually remove specific volumes
+docker volume rm powerrag_powerrag_logs powerrag_oceanbase_data powerrag_powerrag_history_data
+```
+
+**To start fresh after cleanup:**
+
+```bash
+docker compose up -d
+```
+
+#### Viewing Logs and Data
+
+**To view logs from running containers:**
+
+```bash
+# View PowerRAG service logs
+docker compose logs -f powerrag
+
+# View OceanBase database logs
+docker compose logs -f oceanbase
+
+# View all service logs
+docker compose logs -f
+```
+
+**To access logs and data in volumes:**
+
+```bash
+# View log files in the volume
+docker run --rm -v powerrag_powerrag_logs:/data alpine ls -la /data
+
+# Read specific log file
+docker run --rm -v powerrag_powerrag_logs:/data alpine cat /data/ragflow.log
+
+# Access volume data interactively
+docker run --rm -it -v powerrag_oceanbase_data:/data alpine sh
+```
+
+**To copy files from volumes to your host:**
+
+```bash
+# Copy logs from volume to current directory
+docker run --rm -v powerrag_powerrag_logs:/data -v $(pwd):/backup alpine cp -r /data /backup/logs
+
+# Copy database data
+docker run --rm -v powerrag_oceanbase_data:/data -v $(pwd):/backup alpine cp -r /data /backup/db_data
+```
+
 ### Port Already Allocated Error
 
 If you encounter an error like:

docker/README_zh.md

@@ -22,6 +22,8 @@
 - **docker-compose-self-hosted-ob.yml**  
   设置 PowerRAG 及其依赖项的环境，数据库使用自托管 OceanBase 或 SeekDB。
 
+所有配置都使用 **Docker 命名卷** 来持久化数据，确保跨 Linux、Windows 和 macOS 平台的兼容性。配置文件以只读方式从仓库挂载。
+
 程序默认使用 docker-compose.yml，您可以通过 `docker compose -f` 指定配置文件，例如使用自托管数据库启动服务时，可以使用如下命令：
 
 ```shell
@@ -198,6 +200,138 @@ OCEANBASE_DOC_DBNAME=powerrag_doc
 
 ## 🔧 故障排除
 
+### 平台特定注意事项
+
+PowerRAG 的 Docker 部署已设计为可在 Linux、Windows 和 macOS 上无缝工作。Docker Compose 文件使用 **命名 Docker 卷** 进行数据持久化，确保跨平台兼容性。
+
+#### Windows
+
+在 Windows 上运行时，请确保：
+- 安装并运行 **Docker Desktop**，并启用 WSL 2 后端（推荐）
+- 如果遇到配置文件相关的问题，可以检查配置文件（在 `nginx/`、`oceanbase/init.d/` 等目录中）是否使用 **LF 行尾**而不是 CRLF：
+  ```bash
+  git config core.autocrlf false
+  git rm --cached -r .
+  git reset --hard
+  ```
+- 卷挂载中的文件路径由 Docker Desktop 自动处理
+
+#### macOS
+
+在 macOS 上运行时：
+- 安装并运行 **Docker Desktop**
+- 在您的 `.env` 文件中设置 `MACOS` 环境变量：
+  ```dotenv
+  MACOS=1
+  ```
+- 对于 Apple Silicon（M1/M2/M3），Docker 将自动处理平台仿真
+
+#### Linux
+
+Linux 是主要的开发平台，无需额外配置即可工作。
+
+### 卷管理
+
+PowerRAG 使用 Docker 命名卷存储持久化数据（日志、数据库文件、历史数据）。这些卷在容器重启和更新之间保持持久。
+
+#### 多实例部署
+
+Docker Compose 自动为卷名添加项目名称前缀（来自 `.env` 中的 `COMPOSE_PROJECT_NAME`，默认为 `powerrag`）。这允许在同一台机器上运行多个部署而不会发生冲突：
+
+**卷命名示例：**
+- 使用 `COMPOSE_PROJECT_NAME=powerrag`：卷名变为 `powerrag_powerrag_logs`、`powerrag_oceanbase_data` 等
+- 使用 `COMPOSE_PROJECT_NAME=powerrag-dev`：卷名变为 `powerrag-dev_powerrag_logs`、`powerrag-dev_oceanbase_data` 等
+
+**运行多个部署的方法：**
+1. 为每个部署创建单独的目录
+2. 在每个目录的 `.env` 文件中设置唯一的 `COMPOSE_PROJECT_NAME`：
+   ```dotenv
+   COMPOSE_PROJECT_NAME=powerrag-production
+   # 或
+   COMPOSE_PROJECT_NAME=powerrag-dev
+   ```
+3. 每个部署将拥有自己独立的卷集
+
+#### 列出卷
+
+查看所有 PowerRAG 相关的卷：
+```bash
+docker volume ls | grep powerrag
+```
+
+#### 备份卷
+
+在清理或升级之前，您可能需要备份数据：
+
+```bash
+# 备份所有 PowerRAG 卷
+docker run --rm -v powerrag_powerrag_logs:/data -v $(pwd)/backup:/backup alpine tar czf /backup/powerrag_logs.tar.gz -C /data .
+docker run --rm -v powerrag_oceanbase_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/oceanbase_data.tar.gz -C /data .
+docker run --rm -v powerrag_powerrag_history_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/history_data.tar.gz -C /data .
+```
+
+#### 清理卷
+
+> [!WARNING]
+> 删除卷将永久删除所有数据，包括日志、数据库内容和历史记录。请确保先备份重要数据。
+
+**删除所有 PowerRAG 卷和数据：**
+
+```bash
+# 停止并删除所有容器
+docker compose down
+
+# 删除所有 PowerRAG 卷
+docker compose down -v
+
+# 或手动删除特定卷
+docker volume rm powerrag_powerrag_logs powerrag_oceanbase_data powerrag_powerrag_history_data
+```
+
+**清理后重新启动：**
+
+```bash
+docker compose up -d
+```
+
+#### 查看日志和数据
+
+**查看运行中容器的日志：**
+
+```bash
+# 查看 PowerRAG 服务日志
+docker compose logs -f powerrag
+
+# 查看 OceanBase 数据库日志
+docker compose logs -f oceanbase
+
+# 查看所有服务日志
+docker compose logs -f
+```
+
+**访问卷中的日志和数据：**
+
+```bash
+# 查看卷中的日志文件
+docker run --rm -v powerrag_powerrag_logs:/data alpine ls -la /data
+
+# 读取特定日志文件
+docker run --rm -v powerrag_powerrag_logs:/data alpine cat /data/ragflow.log
+
+# 以交互方式访问卷数据
+docker run --rm -it -v powerrag_oceanbase_data:/data alpine sh
+```
+
+**将文件从卷复制到主机：**
+
+```bash
+# 将日志从卷复制到当前目录
+docker run --rm -v powerrag_powerrag_logs:/data -v $(pwd):/backup alpine cp -r /data /backup/logs
+
+# 复制数据库数据
+docker run --rm -v powerrag_oceanbase_data:/data -v $(pwd):/backup alpine cp -r /data /backup/db_data
+```
+
 ### 端口已被占用错误
 
 如果您遇到类似以下的错误：

docker/docker-compose-CN-oc9.yml

@@ -16,7 +16,7 @@ services:
       - 80:80
       - 443:443
     volumes:
-      - ./ragflow-logs:/ragflow/logs
+      - powerrag_logs:/ragflow/logs
       - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf
       - ./nginx/proxy.conf:/etc/nginx/proxy.conf
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf
@@ -41,7 +41,7 @@ services:
       - 80:80
       - 443:443
     volumes:
-      - ./ragflow-logs:/ragflow/logs
+      - powerrag_logs:/ragflow/logs
       - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf
       - ./nginx/proxy.conf:/etc/nginx/proxy.conf
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf
@@ -60,3 +60,7 @@ services:
             - driver: nvidia
               count: all
               capabilities: [gpu]
+
+volumes:
+  powerrag_logs:
+    driver: local

docker/docker-compose-macos.yml

@@ -15,7 +15,7 @@ services:
       - 80:80
       - 443:443
     volumes:
-      - ./ragflow-logs:/ragflow/logs
+      - powerrag_logs:/ragflow/logs
       - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf
       - ./nginx/proxy.conf:/etc/nginx/proxy.conf
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf
@@ -44,3 +44,7 @@ services:
   #   # If you're using Docker Desktop, the --add-host flag is optional. This flag makes sure that the host's internal IP gets exposed to the Prometheus container.
   #   extra_hosts:
   #     - "host.docker.internal:host-gateway"
+
+volumes:
+  powerrag_logs:
+    driver: local

docker/docker-compose-oceanbase.yml

@@ -12,11 +12,11 @@ services:
       - ${SVR_MCP_PORT}:9382 # entry for MCP (host_port:docker_port). The docker_port must match the value you set for `mcp-port` above.
       - ${POWERRAG_SVR_HTTP_PORT:-6000}:6000 # entry for PowerRAG server (host_port:docker_port). The docker_port must match the value you set for `powerrag-port` above.
     volumes:
-      - ./ragflow-logs:/ragflow/logs
+      - powerrag_logs:/ragflow/logs
       - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf
       - ./nginx/proxy.conf:/etc/nginx/proxy.conf
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf
-      - ../history_data_agent:/ragflow/history_data_agent
+      - powerrag_history_data:/ragflow/history_data_agent
       - ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template
       - ./entrypoint.sh:/ragflow/entrypoint.sh
     env_file: .env
@@ -50,8 +50,8 @@ services:
       - OB_SERVER_IP=127.0.0.1
     volumes:
       - ./oceanbase/init.d:/root/boot/init.d
-      - ./oceanbase/data:/root/ob
-      - ./oceanbase/conf:/root/.obd/cluster
+      - oceanbase_data:/root/ob
+      - oceanbase_conf:/root/.obd/cluster
     networks:
       - powerrag
     restart: on-failure
@@ -89,6 +89,16 @@ services:
     networks:
       - powerrag
 
+volumes:
+  powerrag_logs:
+    driver: local
+  powerrag_history_data:
+    driver: local
+  oceanbase_data:
+    driver: local
+  oceanbase_conf:
+    driver: local
+
 networks:
   powerrag:
     driver: bridge