# 星线 Email 技术概览

星线 Email 提供公开邮箱入口、工作空间域名与邮箱管理、网页收发信和管理功能。网页服务负责身份、权限和元数据，邮件协议与邮箱内容由 Mailu、IMAP 和 SMTP 链路承载；网页可打开不等于邮件已能送达外部收件人。

## 入口与架构

公开入口为 [星线 Email](https://stline.cn/)，个人邮箱域名为 `stline.cn`，协议主机默认 `mx.thestarline.cn`。服务端要求 Node.js 24 或以上，使用 TypeScript、Fastify、SQLite、ImapFlow、Nodemailer；客户端使用 React 与 Vite，构建后由同一服务提供静态文件。

| 层 | 主要数据与职责 |
| --- | --- |
| 网页客户端 | 邮箱、文件夹、邮件阅读与编辑、域名和邮箱管理 |
| 平台服务 | 工作空间、成员、会话、域名验证、配额、草稿、审计和发送计数 |
| Mailu 管理接口 | 创建和管理真实域名、邮箱、别名等协议侧资源 |
| IMAP / SMTP | 列表、正文与附件读取，邮件投递请求 |

SQLite 启用 WAL、外键与忙等待，记录工作空间、用户、会话、域名、邮箱、别名、审计、发送用量和注册预留等元数据。邮件正文不能从这些平台表推断为完整备份；正式邮箱内容依赖协议侧存储。本机进程中的工作空间互斥只约束同一服务进程，不是分布式锁。

## 身份、授权与会话

工作空间管理身份与具体邮箱的协议访问凭据分开管理。管理接口按工作空间限制查询和修改，普通邮箱成员不能取得客户管理权限；被暂停的工作空间会被拒绝。邮箱禁用或密码变更会更新认证版本并撤销相关会话，不能继续使用旧的邮箱凭据缓存。

平台会话默认 24 小时，存储令牌摘要；打开邮箱时，服务端将用于协议登录的密码加密后绑定会话与邮箱认证版本，默认 2 小时到期。该机制服务于服务端连接 IMAP/SMTP，不是邮件端到端加密。修改邮箱密码需要当前密码，完成后要求重新登录邮箱。邮箱退出与整个平台会话退出是不同操作。

生产配置拒绝演示模式，要求精确 HTTPS Origin 和合格的凭据加密密钥。默认 IMAP 为 993，SMTP 为 465 并启用 TLS；受信代理范围须显式配置，不能将任意来源都视作可信代理。密钥与 Mailu 管理凭据只属于服务端配置。

## 域名和邮箱的创建流程

1. 客户在工作空间内添加域名，取得 `_starline-verification.<域名>` TXT 验证要求。
2. 服务端查询并核对所有权证明。已被其他工作空间有效占用的域名不能重复认领。
3. 验证通过后调用 Mailu 创建协议侧域名，成功后才进入可用状态。
4. 分别检查 MX、SPF、DKIM、DMARC；所有权验证与投递 DNS 状态是不同结果。
5. 在已启用域名下创建邮箱，检查本地部分、密码与配额；分配总额不能超过工作空间配额。

邮箱本地部分按小写 ASCII 校验，长度 1–64，不接受连续句点。别名目的地址必须是当前工作空间内有效邮箱，最多 50 个；仍被别名引用的邮箱需要先处理引用关系再删除。公开个人邮箱域名受保护，不能由普通客户接管。

## 邮件、草稿与附件

邮件身份由 `folder`、`uidValidity`、`uid` 共同确定，UID 不能当作跨文件夹永久 ID。列表每页读取 50 封；读取、标记和附件请求均重新校验会话、邮箱与文件夹上下文。网页支持回复、全部回复、抄送、密送、转发、星标、归档和草稿。

默认附件总大小配置为 20 MiB，每次最多 10 个文件，仍受上游邮件服务器大小限制。发送时将收件、抄送和密送地址规范化去重，三类合计最多 20 个收件人。草稿按工作空间和邮箱隔离；其字段包括收件人、抄送、密送、主题、文本和附件描述。草稿中的每类地址数组最多 20 项，主题最多 998 字符，文本的字符串长度上限为 1048576，按 JavaScript 字符串长度校验；不能把它直接换算为 UTF-8 字节，也不能把网页限制当作所有外部 SMTP 客户端的限制。

发送计数按收件人数计算，包含网站发送流程中的不确定结果；外部 SMTP 客户端的用量需要协议侧另行限制。SMTP 接受请求只表示上游受理，最终投递、退信和垃圾邮件判定仍可能不同。发送成功后保存“已发送”副本失败时，不能自动重新发送邮件，否则可能造成重复投递。

## PWA、默认值与失败处理

PWA 缓存只覆盖公开页面壳、清单和静态资源，跳过 `/api/`、非 GET 与跨域请求，不缓存邮件、凭据或附件。浏览器本机另存紧凑布局偏好；安装 PWA 不会扩大邮箱权限或启用注册。

个人邮箱默认配额为 1 GiB、网站每日 50 个收件人；生产环境的公开注册默认关闭，是否开放以部署配置与真实验收为准。域名未验证、DNS 查询失败、配额不足、协议认证失效、上游不可用和邮箱禁用必须分别展示，不能用演示数据替代真实结果。健康接口返回进程可用也不能证明对外 SMTP 投递、PTR、DKIM 或第三方中继已验收。

资料依据 2026-10-23 源码整理。部署仍需验证真实 DNS、Mailu 管理、网页及外部客户端收发信、附件和退出重登，不能只凭页面或健康接口判断邮件可用。公开政策见 [隐私中心](https://document.thestarline.cn/privacy/)，使用问题见 [支持中心](https://document.thestarline.cn/support/)。

## 源码依据

实现位于 `mail-platform/server/config.ts`、`app.ts`、`store.ts`、`auth.ts`、`crypto.ts`、`resources.ts`、`domains.ts`、`mail.ts`、`mail-protocol.ts`、`service-health.ts`，以及 `client/src/Pwa.tsx` 和 `client/public/sw.js`。仓库提供单元、协议、容器与端到端验证入口，历史结果应与对应版本和环境一并查看。