diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f357fc3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,208 @@
+# MengStack API
+
+MengStack 是一个基于 Go 的企业级后端框架，采用清晰的分层架构和依赖注入，帮助开发者快速构建高质量的多租户 Web 应用。
+
+## 技术栈
+
+| 组件 | 技术选型 | 说明 |
+|------|---------|------|
+| Web 框架 | [Gin](https://github.com/gin-gonic/gin) | 高性能 HTTP 路由 |
+| ORM | [GORM](https://gorm.io) | PostgreSQL 数据访问 |
+| 缓存 | [go-redis](https://github.com/redis/go-redis) | Redis 客户端 |
+| 依赖注入 | [uber/fx](https://github.com/uber-go/fx) | 生命周期管理 |
+| 配置管理 | [Viper](https://github.com/spf13/viper) | 分层配置 + 环境变量 |
+| 日志 | [Zap](https://github.com/uber-go/zap) | 结构化高性能日志 |
+| 认证 | JWT | Access Token + Refresh Token |
+
+## 架构设计
+
+### 三层隔离
+
+```
+cmd/server/        → 启动层：组装依赖，启动服务
+internal/app/      → 基础设施层：数据库、缓存、中间件、健康检查
+internal/modules/  → 业务模块层：按领域划分的独立模块
+```
+
+### 模块四层结构
+
+每个业务模块遵循统一的四层架构：
+
+```
+modules/auth/
+├── domain/          → 领域层：实体、DTO、仓储接口
+├── application/     → 应用层：业务逻辑、服务实现
+├── infrastructure/  → 基础设施层：仓储实现、数据库迁移
+└── interfaces/      → 接口层：HTTP Handler、路由注册
+```
+
+### 依赖注入
+
+使用 `uber/fx` 管理依赖，每个模块通过 `fx.Provide` 注册，框架自动解析依赖图。生命周期钩子（`fx.Lifecycle`）管理服务器启停，禁止在 Provider 中启动 goroutine。
+
+## 快速开始
+
+### 前置条件
+
+- Go 1.23+
+- PostgreSQL 16+
+- Redis 7+
+
+### 方式一：Docker Compose（推荐）
+
+```bash
+# 克隆项目
+git clone https://mengstackgit.softunis.com/softunis/mengstack-api.git
+cd mengstack-api
+
+# 复制环境变量并修改
+cp .env.example .env
+
+# 一键启动（PostgreSQL + Redis + API）
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f api
+```
+
+### 方式二：本地开发
+
+```bash
+# 1. 启动 PostgreSQL 和 Redis（可用 Docker）
+docker-compose up -d postgres redis
+
+# 2. 复制并编辑配置
+cp .env.example .env
+# 编辑 .env 填入数据库密码等
+
+# 3. 安装依赖
+go mod download
+
+# 4. 启动服务
+make run
+# 或
+go run ./cmd/server
+```
+
+服务启动后访问 `http://localhost:2222/health` 验证。
+
+## 项目结构
+
+```
+mengstack-api/
+├── cmd/server/          # 应用入口
+├── configs/             # 配置模板
+│   ├── config.yaml      # 基础配置
+│   ├── config.dev.yaml  # 开发环境覆盖
+│   └── config.prod.yaml # 生产环境覆盖
+├── internal/
+│   ├── app/             # 基础设施
+│   │   ├── cache/       # Redis 模块
+│   │   ├── database/    # PostgreSQL 模块
+│   │   ├── health/      # 健康检查
+│   │   └── middleware/  # 请求ID、多租户中间件
+│   ├── config/          # 配置加载器
+│   ├── kernel/          # 核心工具（错误、响应、租户上下文）
+│   ├── logger/          # Zap 日志
+│   └── modules/         # 业务模块
+│       └── auth/        # 认证模块（注册/登录/刷新Token）
+├── migrations/          # 数据库迁移脚本
+├── docs/                # Swagger 文档
+├── assets/              # 静态资源（Logo 等）
+├── .env.example         # 环境变量模板
+├── docker-compose.yml   # 容器编排
+├── Makefile             # 常用命令
+└── go.mod               # Go 模块定义
+```
+
+## 配置系统
+
+MengStack 采用三层配置覆盖机制，优先级从低到高：
+
+1. **基础配置** `configs/config.yaml` — 所有环境的默认值
+2. **环境覆盖** `configs/config.{mode}.yaml` — 按 `server.mode` 加载（dev/prod）
+3. **环境变量** `MENGSTACK_` 前缀 — 最高优先级，适合存放密码等敏感信息
+
+```bash
+# 环境变量命名规则：MENGSTACK_{Section}_{Key}
+# 例如：
+MENGSTACK_SERVER_PORT=8080
+MENGSTACK_DATABASE_PASSWORD=your-secret
+MENGSTACK_JWT_SECRET=your-jwt-secret
+```
+
+**安全提示**：永远不要将真实密码提交到 git。使用 `.env` 文件（已加入 `.gitignore`）或系统环境变量。
+
+## 常用命令
+
+```bash
+make build        # 编译二进制
+make run          # 启动开发服务
+make test         # 运行测试
+make test-cover   # 测试覆盖率报告
+make lint         # 代码检查
+make swagger      # 重新生成 Swagger 文档
+make docker-up    # Docker 启动全部服务
+make docker-down  # Docker 停止所有服务
+make clean        # 清理构建产物
+```
+
+## API 概览
+
+### 认证接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/v1/auth/register` | 用户注册 |
+| POST | `/api/v1/auth/login` | 用户登录 |
+| POST | `/api/v1/auth/refresh` | 刷新 Token |
+| GET  | `/api/v1/auth/me` | 获取当前用户（需认证） |
+| GET  | `/health` | 健康检查 |
+
+### 多租户
+
+所有业务接口通过 `X-Tenant-ID` 请求头标识租户。框架自动解析租户上下文并注入到数据库查询中。
+
+完整 API 文档：启动服务后访问 `/swagger/index.html`。
+
+## 添加新模块
+
+以创建 `article` 模块为例：
+
+```
+internal/modules/article/
+├── domain/
+│   ├── entity.go       # Article 实体
+│   ├── dto.go          # 请求/响应 DTO
+│   └── repository.go   # 仓储接口
+├── application/
+│   └── service.go      # 业务逻辑实现
+├── infrastructure/
+│   ├── repository.go   # GORM 仓储实现
+│   └── migrate.go      # AutoMigrate 注册
+└── interfaces/
+    ├── handler.go       # HTTP Handler
+    └── routes.go        # 路由注册（实现 RouteGroup 接口）
+```
+
+1. 创建上述目录和文件
+2. 在 `internal/app/app.go` 中添加 `fx.Provide` 注册新模块
+3. 在 `infrastructure/migrate.go` 中注册 AutoMigrate
+4. 框架自动发现并注册路由
+
+## 开发规范
+
+- **依赖注入**：所有依赖通过 `fx.Provide` 注册，使用 `fx.In` 结构体注入
+- **生命周期**：服务器启停使用 `fx.Lifecycle` 的 `OnStart/OnStop` 钩子
+- **错误处理**：使用 `kernel/errors` 统一错误码
+- **响应格式**：使用 `kernel/response` 统一 JSON 响应结构
+- **日志**：通过 `logger.L()` 获取全局 Zap 实例
+
+## 演示站
+
+- API 地址：https://mengstackdemo.softunis.com
+- Swagger 文档：https://mengstackdemo.softunis.com/swagger/index.html
+
+## 许可证
+
+MIT License