release: v1.7.0

2026-03-15 18:04:16 +08:00
1 parent cb4a119a47
commit 9594cdd443
@@ -1,19 +1,25 @@
 # Outlook Email Plus

-个人自用的 Outlook 邮件管理工具，提供 Web 界面、多账号管理、邮件读取、验证码提取和简单的对外只读 API。
+个人自用的 Outlook 邮件管理与验证码提取工具，提供 Web 界面、多账号统一管理，并支持一组**受控的对外只读 API**（`/api/external/*`）。

-## 核心功能
+适用场景：自用/小团队受控环境，用于管理自己的邮箱、读取邮件、提取验证码/验证链接、对接内部自动化脚本。**不建议直接公网裸露**。

- 多账号统一管理
- Outlook / IMAP 多链路读取
- 验证码和验证链接提取
- Token 定时刷新
- 分组、标签、搜索和批量操作
- 个人自用场景下的对外只读 API
+## 核心能力（现状）
+
+- **多邮箱统一管理**：批量导入、分组、标签、搜索、批量操作
+- **多链路读信**：Microsoft Graph / IMAP（按账号类型与回退策略）
+- **验证码/链接提取**：支持按来源（subject/body/html）、长度范围、正则等策略增强提取稳定性
+- **定时任务**：Token 定时刷新、调度器心跳、Telegram 推送轮询、对外 API 异步探测轮询
+- **Telegram 实时推送（可选）**：后台轮询新邮件并推送到 Telegram，支持 Message-ID 去重与“首次启用不轰炸”策略
+- **临时邮箱（可选）**：对接 GPTMail 临时邮箱服务（生成/刷新/清理/拉取消息）
+- **对外只读 API（可选）**：API Key 鉴权 + 公网模式守卫（IP 白名单、限流、高风险端点可禁用）
+- **安全基线**：敏感数据加密存储、CSRF 防护、登录限速/锁定、审计日志、对外 API 访问审计

 ## 快速开始

-### Docker
+### Docker（推荐）
+
+GHCR：

 ```bash
 docker pull ghcr.io/zeropointsix/outlook-email-plus:latest
@@ -27,7 +33,13 @@ docker run -d \
  ghcr.io/zeropointsix/outlook-email-plus:latest
 ```

-PowerShell:
+Docker Hub（如已同步启用）：
+
+```bash
+docker pull guangshanshui/outlook-email-plus:latest
+```
+
+PowerShell：

 ```powershell
 docker run -d `
@@ -39,6 +51,11 @@ docker run -d `
  ghcr.io/zeropointsix/outlook-email-plus:latest
 ```

+说明：
+
+- 强烈建议将 `data/` 挂载为持久化目录（数据库与运行数据）
+- `SECRET_KEY` 用于会话与敏感字段加密。**丢失后无法解密旧数据**，请妥善保存并保持稳定
+
 ### 本地运行

 ```bash
@@ -47,15 +64,26 @@ pip install -r requirements.txt
 python start.py
 ```

-## 常用配置
+`start.py` 会在缺少 `.env` 时自动从 `.env.example` 复制，并在 `SECRET_KEY` 为空/占位符时自动生成。
+
+## 配置说明
+
+优先通过环境变量或 `.env` 配置（参考 `.env.example`）。常用配置如下：

 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
-| `SECRET_KEY` | 会话密钥，生产环境必须自行设置 | 无 |
-| `LOGIN_PASSWORD` | 后台登录密码 | `admin123` |
-| `PORT` | 监听端口 | `5000` |
+| `SECRET_KEY` | 必填：会话/加密密钥（务必备份） | 无 |
+| `LOGIN_PASSWORD` | 登录密码（首次启动会哈希存储） | `admin123` |
 | `HOST` | 监听地址 | `0.0.0.0` |
+| `PORT` | 监听端口 | `5000` |
 | `DATABASE_PATH` | SQLite 数据库路径 | `data/outlook_accounts.db` |
+| `SCHEDULER_AUTOSTART` | 是否自动启动后台调度器 | `true` |
+| `PROXY_FIX_ENABLED` | 是否启用 ProxyFix（反代部署才需要） | `false` |
+| `TRUSTED_PROXIES` | 受信任代理列表（用于安全解析 `X-Forwarded-For`） | 空 |
+| `GPTMAIL_BASE_URL` | GPTMail 临时邮箱服务地址 | `https://mail.chatgpt.org.uk` |
+| `GPTMAIL_API_KEY` | GPTMail API Key | `gpt-test` |
+| `OAUTH_CLIENT_ID` | OAuth 助手默认 client_id（可选覆盖） | 内置默认值 |
+| `OAUTH_REDIRECT_URI` | OAuth 助手重定向地址（可选覆盖） | `http://localhost:8080` |

 生成 `SECRET_KEY`：

@@ -63,28 +91,61 @@ python start.py
 python -c "import secrets; print(secrets.token_hex(32))"
 ```

-## 使用说明
+## 账号接入与使用

-1. 配置 Outlook 账号的 `client_id` 和 `refresh_token`
-2. 导入邮箱账号
-3. 在页面中查看邮件、提取验证码或管理分组
-4. 如需自动刷新，打开定时刷新配置
+1. 在 Web 页面中添加/导入账号（Outlook 或 IMAP）
+2. Outlook 账号需要 `client_id` 与 `refresh_token`（可在设置中使用 OAuth 助手换取 Refresh Token）
+3. 选择分组/账号后拉取邮件，或直接提取验证码/验证链接
+4. 如需后台能力（定时刷新/Telegram 推送/异步 probe），保持调度器开启（`SCHEDULER_AUTOSTART=true`）

-账号导入的常见格式：
+常见导入格式：

 ```text
 user@outlook.com----password123----client_id----refresh_token
 ```

-## 对外 API
+## 对外只读 API（`/api/external/*`）

-项目提供 `/api/external/*` 只读接口，适合个人自用或受控环境调用。
+对外 API 仅用于**受控环境**调用，统一使用 `X-API-Key` 请求头鉴权（不依赖登录态）。API Key 可在「设置」中配置：

- 邮件列表和邮件详情
- 验证码和验证链接提取
- 健康检查和账号状态查询
+- 兼容旧模式：单个 legacy key（`external_api_key`）
+- 推荐模式：多 Key 管理（可启停/删除、可配置允许访问的邮箱白名单）

-不建议直接公网裸露使用。若需要外部调用，建议至少放在反向代理和受控网络之后。
+常用端点：
+
+- `GET /api/external/health`：健康检查（含版本号）
+- `GET /api/external/capabilities`：能力与受限端点说明
+- `GET /api/external/account-status?email=...`：账号可读性/上游探测摘要
+- `GET /api/external/messages?email=...&folder=inbox&skip=0&top=20`
+- `GET /api/external/messages/latest?email=...`
+- `GET /api/external/messages/<message_id>` / `.../<message_id>/raw`
+- `GET /api/external/verification-code?email=...`
+- `GET /api/external/verification-link?email=...`
+- `GET /api/external/wait-message?email=...&timeout_seconds=30&poll_interval=5`
+  - 同步模式：默认阻塞等待
+  - 异步模式：`mode=async` 返回 `probe_id`（202），再轮询 `GET /api/external/probe/<probe_id>`
+
+最小调用示例：
+
+```bash
+curl -H "X-API-Key: <your-key>" http://localhost:5000/api/external/health
+```
+
+### 公网模式守卫（强烈建议）
+
+如果你确实要在更开放的网络环境使用对外 API，请至少：
+
+1. 通过设置开启「公网模式」
+2. 配置 **IP/CIDR 白名单**（非白名单将返回 403）
+3. 配置 **按 IP 限流**（默认每分钟 60）
+4. 视需要禁用高风险端点：`raw_content`、`wait_message`
+5. 放在反向代理之后，并只在可信代理场景下启用 `PROXY_FIX_ENABLED=true`，同时设置 `TRUSTED_PROXIES`（否则不要信任 `X-Forwarded-For`）
+
+## 开发与测试
+
+```bash
+python -m unittest discover -s tests -v
+```

 ## 界面预览

@@ -97,7 +158,7 @@ user@outlook.com----password123----client_id----refresh_token

 - Flask
 - SQLite
- Microsoft Graph API
+- Microsoft Graph API / IMAP
 - APScheduler
 - 原生 JavaScript

@@ -1,5 +1,33 @@
 # DEVLOG

+## v1.7.0 - 第二次发布：README 交付口径补全
+
+发布日期：2026-03-15
+
+### 新增功能
+
+- 无新增业务功能。本次版本以“对外交付说明与发布内容整理”为主。
+
+### 修复
+
+- 重写 `README.md`，按当前代码实际能力补齐对外说明：对外只读 API、公网模式守卫（IP 白名单/限流/高风险端点禁用）、异步 probe、调度器、反向代理安全配置等。
+
+### 重要变更
+
+- 版本号从 `1.6.1` 提升到 `1.7.0`，应用 UI 侧边栏版本显示、系统/对外 API 返回的 `version` 字段均由 `outlook_web.__version__` 统一驱动。
+- 发布内容继续沿用仓库既有的 Docker 镜像 tar 与源码 zip 作为正式产物。
+
+### 测试/验证
+
+- 单元测试：`python -m unittest discover -s tests -v`
+  - 结果：`Ran 378 tests in 47.899s`
+  - 状态：全部通过
+- 构建验证：`docker build -t outlook-email-plus:v1.7.0 .`
+  - 状态：通过
+- 发布产物：
+  - `dist/outlook-email-plus-v1.7.0-docker.tar`（299,417,600 bytes）
+  - `dist/outlookEmailPlus-v1.7.0-src.zip`（930,706 bytes）
+
 ## v1.6.1 - 发布质量闸门清理与发布内容精简

 发布日期：2026-03-15
@@ -1,4 +1,4 @@
-__version__ = "1.6.1"
+__version__ = "1.7.0"

 from outlook_web.app import create_app