diff --git a/README.md b/README.md
index 2aa79d1..4ca3261 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,137 @@
-# project-template
+# 项目模板 (Project Template)
 
-CI/CD 标准项目模板 - 包含代码检查、构建、镜像推送
\ No newline at end of file
+标准的前后端项目模板，内置完整的 CI/CD 流水线配置。
+
+## 功能特性
+
+- ✅ 代码质量检查 (Lint)
+- ✅ 自动化构建
+- ✅ Docker 镜像构建并推送到 Gitea 私有 Registry
+- ✅ 构建缓存加速
+- ✅ 使用私有基础镜像（无需访问 Docker Hub）
+- ✅ 使用本地 Actions（无需访问 GitHub）
+
+## 快速开始
+
+### 1. 使用模板创建新项目
+
+在 Gitea 界面中：
+1. 点击右上角 **+** → **新建仓库**
+2. 选择 **使用模板创建** → 选择 `project-template`
+3. 填写仓库名称和描述
+4. 点击 **创建仓库**
+
+### 2. 配置 Secrets
+
+在仓库设置中添加以下 Secrets：
+
+| Secret 名称 | 说明 | 示例值 |
+|-----------|------|--------|
+| `GITEA_TOKEN` | 用于推送镜像的访问令牌 | `xxxxxxxxxxxxx` |
+
+> **注意**：`GITEA_TOKEN` 需要有 `write:package` 权限。
+
+### 3. 项目结构
+
+```
+.
+├── .gitea/
+│   └── workflows/
+│       └── ci.yml          # CI/CD 流水线配置
+├── src/                     # 源代码目录
+├── dist/                    # 构建产物（自动生成）
+├── Dockerfile               # Docker 镜像构建
+├── .dockerignore            # Docker 构建忽略文件
+├── .gitignore               # Git 忽略文件
+├── package.json             # 项目配置
+└── README.md                # 项目说明
+```
+
+## CI/CD 流水线说明
+
+### 触发条件
+
+- **Push 到 main / develop 分支**：触发完整流水线
+- **Pull Request 到 main**：触发代码检查和构建（不推送镜像）
+
+### 流水线阶段
+
+1. **Lint & Build**
+   - 检出代码
+   - 安装依赖（带缓存）
+   - 代码风格检查
+   - 类型检查
+   - 项目构建
+   - 上传构建产物
+
+2. **Docker Build & Push**（仅 main 分支）
+   - 下载构建产物
+   - 构建 Docker 镜像
+   - 推送到 Gitea 私有 Registry
+   - 镜像标签：`latest` 和 commit SHA
+
+### 使用的私有资源
+
+**基础镜像**（来自 `git.xiaoxiajianji.com/xiaoxia/base/`）：
+- `node:20` - 构建环境
+- `node:20-alpine` - 生产环境
+
+**Actions**（来自 `actions/` 命名空间）：
+- `actions/checkout@v4` - 代码检出
+- `actions/cache@v4` - 依赖缓存
+- `actions/upload-artifact@v4` - 产物上传
+- `actions/download-artifact@v4` - 产物下载
+- `actions/setup-buildx-action@v3` - Docker Buildx
+- `actions/login-action@v3` - Registry 登录
+- `actions/build-push-action@v6` - 镜像构建推送
+
+## 自定义配置
+
+### 修改 Node.js 版本
+
+修改 `.gitea/workflows/ci.yml` 中的镜像：
+```yaml
+container:
+  image: git.xiaoxiajianji.com/xiaoxia/base/node:22
+```
+
+### 修改构建命令
+
+修改 `package.json` 中的 `scripts` 部分：
+```json
+{
+  "scripts": {
+    "build": "your-build-command",
+    "lint": "your-lint-command"
+  }
+}
+```
+
+### 修改 Dockerfile
+
+根据项目类型（前端/后端/全栈）调整 `Dockerfile` 中的构建和运行步骤。
+
+## 镜像仓库地址
+
+```
+git.xiaoxiajianji.com/<用户名>/<仓库名>
+```
+
+拉取镜像：
+```bash
+docker pull git.xiaoxiajianji.com/xiaoxia/my-project:latest
+```
+
+## 支持的基础镜像
+
+已同步到私有 Registry 的基础镜像：
+
+| 镜像 | 标签 | 用途 |
+|-----|------|------|
+| node | 18, 20, 22 | Node.js 应用 |
+| node | 20-alpine | 轻量 Node.js 运行时 |
+| nginx | alpine, latest | Web 服务器 |
+| python | 3.10-slim, 3.11-slim, 3.12-slim | Python 应用 |
+| postgres | 15-alpine, 16-alpine | 数据库 |
+| redis | 7-alpine | 缓存 |
+| alpine | 3.19, 3.20 | 基础系统 |