diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e9f6a65
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+# 供水管道健康状态与剩余寿命评估系统
+
+用于上传管道数据，完成健康状态和剩余寿命预测，并导出结果表格。系统包含用户认证、邮箱二次认证、管理员用户管理、邀请注册和上传记录下载等功能。
+
+## 主要功能
+
+- 上传 Excel 数据并执行预测，生成结果文件和图像。
+- 用户使用用户名或邮箱登录，陌生设备需完成邮箱二次认证。
+- 支持公开自助注册，也支持管理员在关闭公开注册后发送注册链接。
+- 支持一次性密码重置链接、修改登录邮箱、受信设备管理和会话撤销。
+- 管理员可搜索用户、启停账号、发送密码重置链接、撤销受信设备，以及下载上传记录。
+- 上传记录和用户列表均支持分页。
+
+## 运行要求
+
+- Docker 和 Docker Compose，推荐用于部署。
+- 本机开发建议使用 Python 3.12 和 Conda。
+- 邮件认证、密码重置和邀请注册需要配置 Resend。
+
+## 配置环境变量
+
+复制模板创建实际配置文件：
+
+```bash
+cp .env.example .env
+```
+
+`.env` 用于实际运行配置，不应提交到版本库。`.env.local` 用于本机开发覆盖，空值表示继续使用 `.env` 中的值。优先级为：系统环境变量、`.env.local`、`.env`。
+
+生产环境至少应配置：
+
+```dotenv
+APP_ENV=production
+DEBUG=false
+SECRET_KEY=请填写高强度随机密钥
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=请填写管理员初始密码
+ADMIN_EMAIL=管理员邮箱
+DATABASE_URL=sqlite:////app/data/pipe_survival.db
+RESEND_API_KEY=Resend_API_密钥
+RESEND_FROM_EMAIL=已验证的发件人地址
+SESSION_COOKIE_SECURE=true
+```
+
+可使用下列命令生成 `SECRET_KEY`：
+
+```bash
+python -c "import secrets; print(secrets.token_hex(32))"
+```
+
+其余变量和默认值见 [`.env.example`](.env.example)。其中，`EMAIL_CODE_MINUTES` 控制邮箱验证码有效期，`PASSWORD_RESET_TOKEN_MINUTES` 控制密码重置和邀请注册链接的有效期。
+
+## Docker 部署
+
+### 直接构建
+
+```bash
+docker compose up -d --build
+docker compose logs -f
+```
+
+服务默认监听 `5005` 端口。数据通过以下目录持久化：
+
+| 本机目录 | 容器目录 | 用途 |
+| --- | --- | --- |
+| `./data` | `/app/data` | SQLite 数据库和运行日志 |
+| `./data/uploads` | `/app/uploads` | 已上传的原始文件与预测结果 |
+| `./data/images` | `/app/static/images` | 预测图像 |
+
+不要在更新时使用 `docker compose down -v`，否则可能删除持久化卷。数据库结构会在启动时自动补齐，不会删除现有数据。
+
+### 导入已导出的镜像
+
+将镜像包、`docker-compose.yml` 和 `.env` 放到同一目录后执行：
+
+```bash
+sudo docker load -i pipeline-lifetime_YYYYMMDD.N.tar
+docker compose up -d
+docker compose logs -f
+```
+
+更新镜像时先停止旧容器即可，保留 `data` 目录：
+
+```bash
+docker compose down
+sudo docker load -i pipeline-lifetime_YYYYMMDD.N.tar
+docker compose up -d
+```
+
+## 本机开发
+
+安装 Python 依赖后，使用 `.env.local` 覆盖开发配置：
+
+```bash
+conda create -n pipeline-lifetime python=3.12 -y
+conda activate pipeline-lifetime
+pip install -r requirements.txt
+npm install
+npm run build:css
+python main.py
+```
+
+访问 `http://127.0.0.1:5005`。本机 HTTP 开发时请将 `SESSION_COOKIE_SECURE=false`。修改模板中的 Tailwind 类后，需要执行 `npm run build:css`；持续开发可使用：
+
+```bash
+npm run watch:css
+```
+
+也可使用 Docker 开发覆盖配置：
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+```
+
+## 账户与邮件流程
+
+1. 登录先校验用户名或邮箱、密码和图形验证码。
+2. 未受信设备会收到 6 位邮箱验证码。验证码默认 10 分钟有效，重发间隔默认 60 秒。
+3. 勾选“信任此设备”后，30 天内无需邮箱二次认证。勾选“保持登录状态”后，登录状态最长保持 7 天。
+4. 找回密码会发送一次性重置链接。链接使用后失效，重置成功会撤销其他会话和受信设备。
+5. 管理员可发送注册链接。受邀用户可在公开注册关闭时完成注册，注册链接同样为一次性链接。
+
+邮件服务不可用时，邮箱验证码、密码重置和邀请注册无法完成。请确认 Resend 的 API 密钥、发件人域名和 DNS 验证状态正确。
+
+## 反向代理建议
+
+公开部署建议由 Nginx 提供 HTTPS，并将请求头转发给应用：
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:5005;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+应用会基于当前请求生成密码重置和注册链接。请确保用户访问的公网域名能够正确转发到该服务。
+
+## 测试
+
+```bash
+python -m pytest -q
+```
+
+测试不使用真实 Resend 密钥，也不会发送邮件。