From 0efd9352a095366972691595d2b65e564a9dc19c Mon Sep 17 00:00:00 2001
From: 666ghj <670939375@qq.com>
Date: Thu, 22 Jan 2026 14:35:41 +0800
Subject: [PATCH] feat(docker): add Docker support with Dockerfile,
 docker-compose.yml, and .dockerignore; update README for Docker deployment
 instructions

---
 .dockerignore                      | 23 ++++++++++++++
 .github/workflows/docker-image.yml | 49 ++++++++++++++++++++++++++++++
 Dockerfile                         | 29 ++++++++++++++++++
 README-EN.md                       | 24 ++++++++++++---
 README.md                          | 24 ++++++++++++---
 docker-compose.yml                 | 14 +++++++++
 frontend/package.json              |  2 +-
 7 files changed, 156 insertions(+), 9 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 .github/workflows/docker-image.yml
 create mode 100644 Dockerfile
 create mode 100644 docker-compose.yml

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..0e84a5a
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,23 @@
+.git
+.github
+.gitignore
+.cursor
+.DS_Store
+.env
+
+node_modules
+frontend/node_modules
+backend/.venv
+.venv
+.python-version
+
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+
+frontend/dist
+frontend/.vite
+
+backend/uploads
diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml
new file mode 100644
index 0000000..becbdec
--- /dev/null
+++ b/.github/workflows/docker-image.yml
@@ -0,0 +1,49 @@
+name: Build and push Docker image
+
+on:
+  push:
+    tags: ["*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/mirofish
+          tags: |
+            type=ref,event=tag
+            type=sha
+            type=raw,value=latest
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..e656468
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,29 @@
+FROM python:3.11
+
+# 安装 Node.js （满足 >=18）及必要工具
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends nodejs npm \
+  && rm -rf /var/lib/apt/lists/*
+
+# 从 uv 官方镜像复制 uv
+COPY --from=ghcr.io/astral-sh/uv:0.9.26 /uv /uvx /bin/
+
+WORKDIR /app
+
+# 先复制依赖描述文件以利用缓存
+COPY package.json package-lock.json ./
+COPY frontend/package.json frontend/package-lock.json ./frontend/
+COPY backend/pyproject.toml backend/uv.lock ./backend/
+
+# 安装依赖（Node + Python）
+RUN npm ci \
+  && npm ci --prefix frontend \
+  && cd backend && uv sync --frozen
+
+# 复制项目源码
+COPY . .
+
+EXPOSE 3000 5001
+
+# 同时启动前后端（开发模式）
+CMD ["npm", "run", "dev"]
\ No newline at end of file
diff --git a/README-EN.md b/README-EN.md
index eb2ad0d..c207bc5 100644
--- a/README-EN.md
+++ b/README-EN.md
@@ -87,7 +87,9 @@ Click the image to watch MiroFish's deep prediction of the lost ending based on
 
 ## 🚀 Quick Start
 
-### Prerequisites
+### Option 1: Source Code Deployment (Recommended)
+
+#### Prerequisites
 
 | Tool | Version | Description | Check Installation |
 |------|---------|-------------|-------------------|
@@ -95,7 +97,7 @@ Click the image to watch MiroFish's deep prediction of the lost ending based on
 | **Python** | ≥3.11, ≤3.12 | Backend runtime | `python --version` |
 | **uv** | Latest | Python package manager | `uv --version` |
 
-### 1. Configure Environment Variables
+#### 1. Configure Environment Variables
 
 ```bash
 # Copy the example configuration file
@@ -119,7 +121,7 @@ LLM_MODEL_NAME=qwen-plus
 ZEP_API_KEY=your_zep_api_key
 ```
 
-### 2. Install Dependencies
+#### 2. Install Dependencies
 
 ```bash
 # One-click installation of all dependencies (root + frontend + backend)
@@ -136,7 +138,7 @@ npm run setup
 npm run setup:backend
 ```
 
-### 3. Start Services
+#### 3. Start Services
 
 ```bash
 # Start both frontend and backend (run from project root)
@@ -154,6 +156,20 @@ npm run backend   # Start backend only
 npm run frontend  # Start frontend only
 ```
 
+### Option 2: Docker Deployment
+
+```bash
+# 1. Configure environment variables (same as source deployment)
+cp .env.example .env
+
+# 2. Pull image and start
+docker compose up -d
+```
+
+Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001 (backend)`
+
+> Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed.
+
 ## 📬 Join the Conversation
 
 <div align="center">
diff --git a/README.md b/README.md
index eb49585..8a89a6b 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,9 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体
 
 ## 🚀 快速开始
 
-### 前置要求
+### 一、源码部署（推荐）
+
+#### 前置要求
 
 | 工具 | 版本要求 | 说明 | 安装检查 |
 |------|---------|------|---------|
@@ -95,7 +97,7 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体
 | **Python** | ≥3.11, ≤3.12 | 后端运行环境 | `python --version` |
 | **uv** | 最新版 | Python 包管理器 | `uv --version` |
 
-### 1. 配置环境变量
+#### 1. 配置环境变量
 
 ```bash
 # 复制示例配置文件
@@ -119,7 +121,7 @@ LLM_MODEL_NAME=qwen-plus
 ZEP_API_KEY=your_zep_api_key
 ```
 
-### 2. 安装依赖
+#### 2. 安装依赖
 
 ```bash
 # 一键安装所有依赖（根目录 + 前端 + 后端）
@@ -136,7 +138,7 @@ npm run setup
 npm run setup:backend
 ```
 
-### 3. 启动服务
+#### 3. 启动服务
 
 ```bash
 # 同时启动前后端（在项目根目录执行）
@@ -154,6 +156,20 @@ npm run backend   # 仅启动后端
 npm run frontend  # 仅启动前端
 ```
 
+### 二、Docker 部署
+
+```bash
+# 1. 配置环境变量（同源码部署）
+cp .env.example .env
+
+# 2. 拉取镜像并启动
+docker compose up -d
+```
+
+默认会读取根目录下的 `.env`，并映射端口 `3000（前端）/5001（后端）`
+
+> 在 `docker-compose.yml` 中已通过注释提供加速镜像地址，可按需替换
+
 ## 📬 更多交流
 
 <div align="center">
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..637f1df
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,14 @@
+services:
+  mirofish:
+    image: ghcr.io/666ghj/mirofish:latest
+    # 加速镜像（如拉取缓慢可替换上方地址）
+    # image: ghcr.nju.edu.cn/666ghj/mirofish:latest
+    container_name: mirofish
+    env_file:
+      - .env
+    ports:
+      - "3000:3000"
+      - "5001:5001"
+    restart: unless-stopped
+    volumes:
+      - ./backend/uploads:/app/backend/uploads
\ No newline at end of file
diff --git a/frontend/package.json b/frontend/package.json
index 8a63106..f7e995a 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -4,7 +4,7 @@
   "version": "0.1.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
+    "dev": "vite --host",
     "build": "vite build",
     "preview": "vite preview"
   },