diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..aa185db
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,50 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info
+.eggs
+dist
+build
+
+# 虚拟环境
+.venv
+venv
+env
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# 环境变量（部署时通过 compose 或运行时注入）
+.env
+.env.*
+!.env.example
+
+# 日志与临时文件
+*.log
+webIOs/output/logs/*
+!webIOs/output/logs/.gitkeep
+
+# 测试
+.pytest_cache
+.coverage
+htmlcov
+test/
+
+# 文档
+*.md
+!README.md
+
+# 本地数据（生产应使用 volume 挂载）
+data/chroma/*
+data/uploads/*
+!data/.gitkeep
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..8102ef9
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,12 @@
+# 数据库（Docker 部署时由 docker-compose 注入，本地开发可覆盖）
+# DATABASE_URL=postgresql+asyncpg://drgraph:yingping@localhost:5432/th_agenter
+# 若使用 MySQL：DATABASE_URL=mysql+aiomysql://user:pass@localhost:3306/dbname?charset=utf8mb4
+
+# JWT 密钥（生产环境务必修改）
+# SECRET_KEY=your-secret-key-here-change-in-production
+
+# 大模型 API（按需配置）
+# OPENAI_API_KEY=
+# DEEPSEEK_API_KEY=
+# DOUBAO_API_KEY=
+# ZHIPU_API_KEY=
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..e663d18
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,27 @@
+# TH Agenter 后端 Docker 镜像
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# 安装系统依赖（PDF、文档处理等）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# 复制依赖文件（排除 Windows 专用包 win32_setctime）
+COPY requirements.txt .
+RUN grep -v '^win32_setctime' requirements.txt > /tmp/requirements.txt \
+    && pip install --no-cache-dir -r /tmp/requirements.txt
+
+# 复制项目代码
+COPY . .
+
+# 创建数据目录
+RUN mkdir -p /app/data/uploads /app/data/chroma /app/webIOs/output/logs
+
+# 暴露端口
+EXPOSE 8000
+
+# 启动命令：先执行数据库迁移，再启动 uvicorn
+CMD ["sh", "-c", "alembic upgrade head 2>/dev/null || true && uvicorn main:app --host 0.0.0.0 --port 8000"]
diff --git a/docker-compose.yml b/docker-compose.yml
index 180e465..0b3d489 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -11,7 +11,30 @@ services:
     volumes:
       - pgdata:/var/lib/postgresql/data
     restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U drgraph -d th_agenter"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  app:
+    build: .
+    container_name: hyf-backend
+    ports:
+      - "8000:8000"
+    environment:
+      DATABASE_URL: postgresql+asyncpg://drgraph:yingping@db:5432/th_agenter
+    volumes:
+      - ./data/uploads:/app/data/uploads
+      - ./data/chroma:/app/data/chroma
+      - ./webIOs/output/logs:/app/webIOs/output/logs
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
 
 volumes:
   pgdata:
-  # docker exec -it pgvector-db psql -U drgraph -d th_agenter
+
+# 首次部署需在数据库创建 pgvector 扩展：
+# docker exec -it pgvector-db psql -U drgraph -d th_agenter -c "CREATE EXTENSION IF NOT EXISTS vector;"
diff --git a/scripts/DOCKER.md b/scripts/DOCKER.md
new file mode 100644
index 0000000..931edc8
--- /dev/null
+++ b/scripts/DOCKER.md
@@ -0,0 +1,41 @@
+# Docker 部署说明
+
+## 快速启动
+
+```bash
+# 构建并启动
+docker compose up -d --build
+
+# 首次部署需创建 pgvector 扩展（若使用向量检索）
+docker exec -it pgvector-db psql -U drgraph -d th_agenter -c "CREATE EXTENSION IF NOT EXISTS vector;"
+
+# 执行数据库迁移（首次或模型变更后）
+docker exec -it hyf-backend alembic upgrade head
+```
+
+## 服务说明
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| app  | 8000 | FastAPI 后端 |
+| db   | 5432 | PostgreSQL + pgvector |
+
+## 数据持久化
+
+- `./data/uploads` - 知识库上传文件
+- `./data/chroma` - 向量数据库（Chroma 本地存储）
+- `./webIOs/output/logs` - 应用日志
+
+## 环境变量
+
+通过 `docker-compose.yml` 的 `environment` 或 `.env` 文件配置，常用：
+
+- `DATABASE_URL` - 数据库连接（compose 已默认配置）
+- `SECRET_KEY` - JWT 密钥（生产务必修改）
+- 大模型 API 密钥等（见 `.env.example`）
+
+## 仅构建镜像
+
+```bash
+docker build -t hyf-backend:latest .
+```