docs(README): 重写项目说明与部署文档
- 更新技术栈徽标与项目简介，补充 TypeScript、Dovecot 等信息。 - 重构功能特性、目录结构、环境要求、快速开始和首次部署清单。 - 补充关键环境变量、架构说明、邮件流转、开发验证与生产注意事项。
This commit is contained in:
LanQin
@@ -1,107 +1,196 @@
|
|||||||
# LanQin Email
|
# LanQin Email
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
自建邮箱 Webmail 全栈方案。前端 React + shadcn/ui，后端 Go + SQLite，默认单容器集成 Postfix、Dovecot、Rspamd。
|
LanQin Email 是一个自建邮箱 Webmail 全栈方案：前端使用 React + TypeScript + shadcn/ui，后端使用 Go + SQLite，部署时可用单容器集成 API、Web、Nginx、Postfix、Dovecot、Rspamd。
|
||||||
|
|
||||||
## 特性
|
## 功能特性
|
||||||
|
|
||||||
- **Webmail 客户端** — 文件夹管理、邮件读写、附件、搜索、标签、星标、规则过滤
|
- **Webmail 客户端**：多邮箱切换、文件夹、邮件读写、草稿、定时发送、附件、搜索、标签、星标、移动/删除、已读/未读。
|
||||||
- **多域名/多邮箱** — 域名管理、DKIM 签名、DNS 记录检测、邮箱别名转发
|
- **邮箱增强**：联系人、签名、收件规则、发件人黑名单、邮件统计、归档已读、清空回收站/垃圾邮件。
|
||||||
- **双因素认证** — TOTP 两步登录（兼容 Google Authenticator / Authy）
|
- **多域名/多邮箱**：域名管理、DKIM 密钥生成、DNS 记录展示与检测、邮箱账号、别名转发、无人收件开关。
|
||||||
- **管理员面板** — 用户/域名/邮箱/别名/邮件管理、系统设置、邮件模板
|
- **账号与权限**：登录/注册、会话管理、TOTP 两步验证、Cloudflare Turnstile、用户自助申请邮箱、权限组/RBAC。
|
||||||
- **用户自助** — 开放注册、自助申请邮箱、黑名单、收件规则、联系人
|
- **管理员面板**：概览清单、用户/权限组/域名/邮箱/别名/全部邮件管理、系统设置、邮件模板、SMTP 测试。
|
||||||
- **单容器部署** — 一个容器跑通 API + Web + Nginx + Postfix + Dovecot + Rspamd
|
- **邮件服务栈**：Postfix 投递、Dovecot IMAP/POP3、Rspamd 反垃圾与 DKIM 签名、Maildir 到 SQLite 同步。
|
||||||
- **本地投递** — 开发环境系统内邮箱互发直接写入 Inbox，无需公网邮件栈
|
- **部署友好**：默认 all-in-one 单容器，也提供多容器 stack 方便调试 Postfix/Dovecot/Rspamd。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
.
|
||||||
|
├── apps/api # Go API、SQLite schema、邮件同步与业务逻辑
|
||||||
|
├── apps/web # React/Vite Webmail 与管理后台
|
||||||
|
├── deploy # Docker Compose、镜像构建、Postfix/Dovecot/Rspamd 配置
|
||||||
|
└── .github/workflows # Docker 镜像发布流水线
|
||||||
|
```
|
||||||
|
|
||||||
|
## 环境要求
|
||||||
|
|
||||||
|
### 开发环境
|
||||||
|
|
||||||
|
- Go 1.25+
|
||||||
|
- Node.js 20+
|
||||||
|
- pnpm 10.28.2（可通过 corepack 启用）
|
||||||
|
|
||||||
|
### 部署环境
|
||||||
|
|
||||||
|
- Docker Engine
|
||||||
|
- Docker Compose v2
|
||||||
|
- 可解析的邮件域名，以及可用的 25 / 465 / 587 / 993 / 995 等端口
|
||||||
|
|
||||||
|
> 公网收发邮件还需要正确配置 MX、SPF、DKIM、DMARC，并确认云厂商未封禁 SMTP 端口。
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
|
|
||||||
### 开发
|
### 本地开发
|
||||||
|
|
||||||
|
后端：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 后端
|
|
||||||
cd apps/api
|
cd apps/api
|
||||||
go mod tidy
|
go mod download
|
||||||
go test ./...
|
go test ./...
|
||||||
go run ./cmd/server
|
go run ./cmd/server
|
||||||
|
```
|
||||||
|
|
||||||
# 前端（新终端）
|
前端（新终端）：
|
||||||
|
|
||||||
|
```bash
|
||||||
cd apps/web
|
cd apps/web
|
||||||
|
corepack enable
|
||||||
|
corepack prepare pnpm@10.28.2 --activate
|
||||||
pnpm install
|
pnpm install
|
||||||
pnpm run dev
|
pnpm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
默认管理员：`admin@lanqin.local`，密码通过 `LANQIN_ADMIN_PASSWORD` 设置（不设置则启动时随机生成并输出到日志）。
|
访问：
|
||||||
|
|
||||||
### 部署
|
- Web：`http://localhost:5173`
|
||||||
|
- API：`http://localhost:8080`
|
||||||
|
|
||||||
服务器只需要 Compose 文件和配置，不需要源码构建：
|
默认管理员邮箱为 `admin@lanqin.local`。建议开发时显式设置 `LANQIN_ADMIN_PASSWORD`；如果未设置，后端首次启动会随机生成密码并输出到日志。
|
||||||
|
|
||||||
|
### Docker 部署（单容器）
|
||||||
|
|
||||||
|
服务器只需要 `deploy/` 下的 Compose 文件和配置，不需要源码构建：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd deploy
|
cd deploy
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
# 修改 .env 里的域名和管理员密码
|
# 修改 .env：域名、访问地址、管理员邮箱、管理员密码等
|
||||||
docker compose pull
|
docker compose pull
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
单容器内部集成：API、Web、Nginx、Postfix、Dovecot、Rspamd。
|
常用命令：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看日志
|
||||||
|
docker compose logs -f lanqin-email
|
||||||
|
|
||||||
|
# 更新镜像并重启
|
||||||
|
docker compose pull
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# 停止服务
|
||||||
|
docker compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
如需在完整源码仓库中本地构建镜像：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd deploy
|
||||||
|
cp .env.example .env
|
||||||
|
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
更多部署细节见 [`deploy/README.md`](./deploy/README.md)。
|
||||||
|
|
||||||
|
## 首次部署清单
|
||||||
|
|
||||||
|
1. 编辑 `deploy/.env`：至少修改 `LANQIN_PUBLIC_HOSTNAME`、`LANQIN_PUBLIC_BASE_URL`、`LANQIN_ADMIN_EMAIL`、`LANQIN_ADMIN_PASSWORD`。
|
||||||
|
2. 生产环境建议挂载真实 TLS 证书，并设置 `LANQIN_TLS_CERT_FILE` / `LANQIN_TLS_KEY_FILE`。
|
||||||
|
3. 登录管理后台，添加邮件域名。
|
||||||
|
4. 在域名管理中复制并配置 MX、SPF、DKIM、DMARC 记录，然后点击 DNS 检测。
|
||||||
|
5. 创建邮箱账号、别名转发或权限组，按需开启注册、2FA、Turnstile、自助申请邮箱。
|
||||||
|
6. 使用后台 SMTP 测试与 Webmail 收发测试确认链路正常。
|
||||||
|
|
||||||
|
## 关键环境变量
|
||||||
|
|
||||||
|
完整配置见 [`deploy/.env.example`](./deploy/.env.example)。常用变量如下：
|
||||||
|
|
||||||
|
| 变量 | 说明 | 默认/示例 |
|
||||||
|
|------|------|-----------|
|
||||||
|
| `LANQIN_IMAGE` | all-in-one 镜像 | `ghcr.io/lanqin996/lanqin-email:latest` |
|
||||||
|
| `LANQIN_PUBLIC_HOSTNAME` | 邮件服务器主机名，影响 Postfix/DNS 展示/链接 | `mail.example.com` |
|
||||||
|
| `LANQIN_PUBLIC_BASE_URL` | Webmail 对外访问地址 | `https://mail.example.com` |
|
||||||
|
| `LANQIN_ADMIN_EMAIL` | 初始管理员邮箱 | `admin@example.com` |
|
||||||
|
| `LANQIN_ADMIN_PASSWORD` | 初始管理员密码，生产必须修改 | `ChangeMe123!` |
|
||||||
|
| `LANQIN_DB_PATH` | SQLite 数据库路径 | `/data/lanqin.db` |
|
||||||
|
| `LANQIN_ALLOW_INSECURE_HTTP` | 是否允许非 HTTPS Cookie，本地调试可开 | `false` |
|
||||||
|
| `LANQIN_OPEN_REGISTRATION` | 是否开放注册 | `false` |
|
||||||
|
| `LANQIN_TWO_FACTOR_ENABLED` | 2FA 功能总开关 | `false` |
|
||||||
|
| `LANQIN_TURNSTILE_ENABLED` | 是否启用 Turnstile | `false` |
|
||||||
|
| `LANQIN_SMTP_HOST` / `LANQIN_SMTP_PORT` | Webmail 发信 SMTP | `127.0.0.1` / `25` |
|
||||||
|
| `LANQIN_MAILDIR_ROOT` | Maildir 根目录 | `/var/mail/vhosts` |
|
||||||
|
| `LANQIN_CATCH_ALL_ENABLED` | 未注册收件地址是否进入全部邮件 | `false` |
|
||||||
|
| `LANQIN_USER_MAILBOX_APPLY_ENABLED` | 是否允许用户自助申请邮箱 | `false` |
|
||||||
|
|
||||||
## 架构
|
## 架构
|
||||||
|
|
||||||
```
|
```text
|
||||||
┌─────────────────────────────────────────────────┐
|
┌────────────────────────────────────────────────────────────┐
|
||||||
│ Docker 容器 │
|
│ lanqin-email 单容器 │
|
||||||
│ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │
|
│ │
|
||||||
│ │ API │ │ Web │ │Nginx │ │ Postfix │ │
|
│ ┌─────────┐ ┌────────────┐ ┌──────────────┐ │
|
||||||
│ │ Go │ │ React │ │反代 │ │ MTA │ │
|
│ │ Nginx │ ───▶ │ Go API │ ───▶ │ SQLite /data │ │
|
||||||
│ └──┬───┘ └────────┘ └──────┘ └────┬─────┘ │
|
│ │ Web 静态│ │ Webmail API│ └──────┬───────┘ │
|
||||||
│ │ SQLite Maildir │ │
|
│ └─────────┘ └─────┬──────┘ │ │
|
||||||
│ └──────────────────────────────────┘ │
|
│ │ Maildir sync │ maps │
|
||||||
│ ┌────────┐ ┌──────────┐ │
|
│ ┌─────────┐ ┌─────▼──────┐ ┌──────▼───────┐ │
|
||||||
│ │Dovecot │ │ Rspamd │ │
|
│ │ Rspamd │ ◀───▶ │ Postfix │ ───▶ │ Dovecot/LMTP │ │
|
||||||
│ │ IMAP │ │ 反垃圾 │ │
|
│ │ DKIM/AS │ │ SMTP/MTA │ │ IMAP/POP3 │ │
|
||||||
│ └────────┘ └──────────┘ │
|
│ └─────────┘ └────────────┘ └──────────────┘ │
|
||||||
└─────────────────────────────────────────────────┘
|
└────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
数据流：
|
邮件流转：
|
||||||
1. **收件** → Postfix 接收 → Dovecot 写入 Maildir → API worker 同步到 SQLite → Webmail 展示
|
|
||||||
2. **发件** → Webmail 编辑 → API 构造 MIME → Postfix 投递
|
|
||||||
3. **反垃圾** → Rspamd 在 Postfix 投递前评分，标记 Spam 文件夹
|
|
||||||
|
|
||||||
## 能力
|
1. **收件**：Postfix 接收邮件 → Rspamd 评分/标记 → Dovecot 写入 Maildir → API worker 同步到 SQLite → Webmail 展示。
|
||||||
|
2. **发件**：Webmail 调用 API → API 构造 MIME → SMTP 提交给 Postfix 或外部 SMTP → 投递到目标地址。
|
||||||
|
3. **本地投递**：开发环境中，系统内邮箱互发可直接写入对方 Inbox；未配置 `LANQIN_SMTP_HOST` 时不会真正投递外部收件人。
|
||||||
|
4. **第三方客户端**：可通过 SMTP 465/587、IMAP 993、POP3 995 连接；生产环境请配置匹配 `LANQIN_PUBLIC_HOSTNAME` 的证书。
|
||||||
|
|
||||||
| 模块 | 功能 |
|
## 开发与验证
|
||||||
|------|------|
|
|
||||||
| 认证 | 登录/注册、会话管理、双因素 TOTP、Turnstile 人机验证 |
|
|
||||||
| 域名 | 多域名管理、DKIM 密钥生成、DNS 记录展示与检测 |
|
|
||||||
| 邮箱 | 邮箱账号管理、容量配额、密码同步 |
|
|
||||||
| Webmail | 文件夹、邮件列表、阅读、写信、附件、搜索、已读/未读、星标、移动、删除、标签 |
|
|
||||||
| 规则 | 收件规则（条件+动作）、发件人黑名单 |
|
|
||||||
| 联系人 | 个人通讯录管理 |
|
|
||||||
| 管理 | 用户/域名/邮箱/别名 CRUD、系统设置持久化、邮件模板编辑、SMTP 测试 |
|
|
||||||
| 清理 | 归档已读、清空回收站/垃圾邮件 |
|
|
||||||
|
|
||||||
## 收发说明
|
```bash
|
||||||
|
# API 测试
|
||||||
|
cd apps/api
|
||||||
|
go test ./...
|
||||||
|
|
||||||
- **开发环境**：系统内邮箱互发直接投递到对方 Inbox。未配置 `LANQIN_SMTP_HOST` 时外部收件人不会真正投递。
|
# Web 检查与构建
|
||||||
- **服务器部署**：`.env` 默认 `LANQIN_SMTP_HOST=127.0.0.1`，发件交给同容器内 Postfix。
|
cd apps/web
|
||||||
- **收件同步**：Postfix/Dovecot 收到 Maildir 后，API 的 Maildir worker 同步到 SQLite 后展示。
|
pnpm run check
|
||||||
- **公网收发**：需要正确配置 MX/SPF/DKIM/DMARC，并确认云厂商开放 25/587/993 端口。
|
|
||||||
|
|
||||||
## 要求
|
# 单容器源码构建验证
|
||||||
|
cd deploy
|
||||||
|
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
- Go 1.22+
|
## 生产注意事项
|
||||||
- Node.js 20+
|
|
||||||
- Docker & Docker Compose（部署）
|
- 生产环境必须修改默认管理员密码，并妥善保管 `.env`、SQLite 数据库、Maildir 与 DKIM 私钥。
|
||||||
|
- Web 可放在宿主机 Nginx/宝塔/边缘网关后，但 SMTP/IMAP/POP3 证书需要单独挂载给容器内 Postfix/Dovecot。
|
||||||
|
- 云厂商常默认封禁 25 端口；无法收发公网邮件时先检查端口、安全组、防火墙与反向 DNS。
|
||||||
|
- SQLite 适合单机部署；多节点部署前需要迁移数据库，并同步调整 Postfix/Dovecot 查询配置。
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[MIT](./LICENSE)
|
[MIT](./LICENSE)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user