diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fa805da
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# IPTV Playlist Aggregator（IPTV 播放列表聚合）
+
+为解决中国大陆访问 GitHub 不稳定的问题，本项目作为 [iptv-org/iptv](https://github.com/iptv-org/iptv.git) 的镜像中转站而构建。原项目收集、整理全球免费 IPTV 直播源，按多维度分类生成 M3U 播放列表。
+
+## 项目结构
+
+```
+.
+├── index.m3u                  # 全量聚合播放列表
+├── index.category.m3u         # 按分类索引
+├── index.country.m3u          # 按国家/地区索引
+├── index.language.m3u         # 按语言索引
+├── categories/                # 按内容类型分类（新闻、体育、电影等）
+├── countries/                 # 按国家/地区代码分类（cn、us、jp 等）
+├── languages/                 # 按语言代码分类（zho、eng、jpn 等）
+├── regions/                   # 按地理区域分类（eu、asia、latam 等）
+├── cities/                    # 按城市分类
+├── subdivisions/              # 按行政区划分分类
+├── sources/                   # 按来源/平台分类（pluto、samsung 等）
+├── raw/                       # 原始数据
+├── docker-compose.yml         # Docker 部署配置
+└── .gitea/workflows/deploy.yml # 自动部署工作流
+```
+
+## 分支说明
+
+### `main` —— 本地/内网部署分支
+
+- **用途**：本地开发、测试以及内网（Gitea Actions）自动部署。
+- **工作流**：推送代码到 `main` 分支后，Gitea Actions 自动将 M3U 文件同步到本地服务器，并通过 Docker Compose 启动 Nginx 对外提供静态文件服务。
+- **部署方式**：使用 `docker-compose.yml` 拉取 Nginx Alpine 镜像，将 `site/` 目录挂载为 Web 根目录，监听 `65500` 端口。
+
+### `cloud` —— 上游同步分支
+
+- **用途**：定时从上游项目 [iptv-org/iptv](https://github.com/iptv-org/iptv.git) 拉取最新代码，并将同步结果推送回 Gitea 镜像仓库。
+- **注意**：启动之前需要修改`.env`文件的`GITEA_TOKEN`字段。
+
+## 本地运行
+
+```bash
+# 将 M3U 文件复制到 site 目录
+mkdir -p site
+cp -r categories countries languages regions cities subdivisions sources raw *.m3u site/
+
+# 启动 Nginx 服务
+docker compose up -d
+```
+
+访问 `http://localhost:65500` 即可获取播放列表。
+
+## 使用方式
+
+在支持 M3U 的 IPTV 播放器（如 VLC、Kodi、IPTV Smarters 等）中添加以下地址：
+
+```
+http://<你的服务器地址>:65500/index.m3u
+```
+
+也可以按需加载分类列表，例如：
+
+```
+http://<你的服务器地址>:65500/countries/cn.m3u       # 中国地区直播源
+http://<你的服务器地址>:65500/categories/sports.m3u   # 体育频道
+http://<你的服务器地址>:65500/languages/zho.m3u       # 中文频道
+```