docs(README): 重写项目介绍与部署说明
- 补充技术栈徽章、功能特性与架构概览。 - 重新整理开发启动、部署流程与收发说明。 - 更新环境要求与默认管理员配置说明。
This commit is contained in:
LanQin_
@@ -1,50 +1,46 @@
|
||||
# LanQin Email
|
||||
|
||||
LanQin Email 是一个自建邮箱 Webmail MVP：React/Vite + shadcn 风格组件前端，Go + SQLite 后端，默认使用单容器集成 Postfix、Dovecot、Rspamd。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 快速开发
|
||||
自建邮箱 Webmail 全栈方案。前端 React + shadcn/ui，后端 Go + SQLite，默认单容器集成 Postfix、Dovecot、Rspamd。
|
||||
|
||||
### 后端
|
||||
## 特性
|
||||
|
||||
- **Webmail 客户端** — 文件夹管理、邮件读写、附件、搜索、标签、星标、规则过滤
|
||||
- **多域名/多邮箱** — 域名管理、DKIM 签名、DNS 记录检测、邮箱别名转发
|
||||
- **双因素认证** — TOTP 两步登录（兼容 Google Authenticator / Authy）
|
||||
- **管理员面板** — 用户/域名/邮箱/别名/邮件管理、系统设置、邮件模板
|
||||
- **用户自助** — 开放注册、自助申请邮箱、黑名单、收件规则、联系人
|
||||
- **单容器部署** — 一个容器跑通 API + Web + Nginx + Postfix + Dovecot + Rspamd
|
||||
- **本地投递** — 开发环境系统内邮箱互发直接写入 Inbox，无需公网邮件栈
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 开发
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
cd apps/api
|
||||
go mod tidy
|
||||
go test ./...
|
||||
go run ./cmd/server
|
||||
```
|
||||
|
||||
默认管理员：
|
||||
|
||||
- 邮箱：`admin@lanqin.local`
|
||||
- 密码：`ChangeMe123!`
|
||||
|
||||
生产环境请通过 `LANQIN_ADMIN_PASSWORD` 覆盖。
|
||||
|
||||
### 前端
|
||||
|
||||
```bash
|
||||
# 前端（新终端）
|
||||
cd apps/web
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
前端默认代理 `/api` 到 `http://localhost:8080`。
|
||||
默认管理员：`admin@lanqin.local`，密码通过 `LANQIN_ADMIN_PASSWORD` 设置（不设置则启动时随机生成并输出到日志）。
|
||||
|
||||
### Web UI 规则
|
||||
### 部署
|
||||
|
||||
`apps/web` 的业务页面和业务组件必须使用官方 shadcn/ui 组件源码。新增 UI primitive 前先执行：
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
npx shadcn@latest add <component>
|
||||
npm run check:shadcn
|
||||
```
|
||||
|
||||
详细规则见 `apps/web/SHADCN_RULES.md`。`npm run check:shadcn` 是提交前的实际检查入口。
|
||||
|
||||
## Docker 部署
|
||||
|
||||
推荐单容器部署。服务器只需要 `deploy/docker-compose.yml` 和 `.env`，不需要源码构建：
|
||||
服务器只需要 Compose 文件和配置，不需要源码构建：
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
@@ -54,44 +50,53 @@ docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
这个容器内部集成：API、Web、Nginx、Postfix、Dovecot、Rspamd。
|
||||
单容器内部集成：API、Web、Nginx、Postfix、Dovecot、Rspamd。
|
||||
|
||||
如果 GHCR 镜像是私有的，先登录：
|
||||
## 架构
|
||||
|
||||
```bash
|
||||
echo "<github_token>" | docker login ghcr.io -u <github_user> --password-stdin
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Docker 容器 │
|
||||
│ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │
|
||||
│ │ API │ │ Web │ │Nginx │ │ Postfix │ │
|
||||
│ │ Go │ │ React │ │反代 │ │ MTA │ │
|
||||
│ └──┬───┘ └────────┘ └──────┘ └────┬─────┘ │
|
||||
│ │ SQLite Maildir │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ ┌────────┐ ┌──────────┐ │
|
||||
│ │Dovecot │ │ Rspamd │ │
|
||||
│ │ IMAP │ │ 反垃圾 │ │
|
||||
│ └────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
本地源码构建：
|
||||
数据流：
|
||||
1. **收件** → Postfix 接收 → Dovecot 写入 Maildir → API worker 同步到 SQLite → Webmail 展示
|
||||
2. **发件** → Webmail 编辑 → API 构造 MIME → Postfix 投递
|
||||
3. **反垃圾** → Rspamd 在 Postfix 投递前评分，标记 Spam 文件夹
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
cp .env.example .env
|
||||
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
|
||||
```
|
||||
## 能力
|
||||
|
||||
如需多容器调试版：
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| 认证 | 登录/注册、会话管理、双因素 TOTP、Turnstile 人机验证 |
|
||||
| 域名 | 多域名管理、DKIM 密钥生成、DNS 记录展示与检测 |
|
||||
| 邮箱 | 邮箱账号管理、容量配额、密码同步 |
|
||||
| Webmail | 文件夹、邮件列表、阅读、写信、附件、搜索、已读/未读、星标、移动、删除、标签 |
|
||||
| 规则 | 收件规则（条件+动作）、发件人黑名单 |
|
||||
| 联系人 | 个人通讯录管理 |
|
||||
| 管理 | 用户/域名/邮箱/别名 CRUD、系统设置持久化、邮件模板编辑、SMTP 测试 |
|
||||
| 清理 | 归档已读、清空回收站/垃圾邮件 |
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
docker compose -f docker-compose.stack.yml -f docker-compose.stack.build.yml up -d --build
|
||||
```
|
||||
## 收发说明
|
||||
|
||||
真实公网收发前需要正确配置 MX/SPF/DKIM/DMARC，并确认云厂商开放 25/587/993 端口。
|
||||
|
||||
## V1 能力
|
||||
|
||||
- 管理员/普通用户登录
|
||||
- 多域名、邮箱账号、别名管理
|
||||
- DNS 记录展示和检测
|
||||
- Webmail：文件夹、邮件列表、阅读、写信、附件、搜索、已读、星标、移动、删除
|
||||
- 开发环境本地投递：给系统内邮箱发送会直接写入对方 Inbox，便于无公网邮件栈验证
|
||||
|
||||
## 当前收发说明
|
||||
|
||||
- 本地开发：系统内邮箱互发可直接使用；未配置 `LANQIN_SMTP_HOST` 时，外部收件人不会真正投递到公网。
|
||||
- 服务器部署：`deploy/.env.example` 默认使用 `LANQIN_SMTP_HOST=127.0.0.1`，发件会交给同容器内 Postfix。
|
||||
- 收件同步：Postfix/Dovecot 收到的 Maildir 邮件会由 API 的 Maildir worker 同步到 SQLite 后展示在 Webmail。
|
||||
- Maildir worker 通过 `LANQIN_MAILDIR_ROOT` 和 `LANQIN_MAILDIR_SCAN_SECONDS` 控制，默认服务器路径为 `/var/mail/vhosts`。
|
||||
- **开发环境**：系统内邮箱互发直接投递到对方 Inbox。未配置 `LANQIN_SMTP_HOST` 时外部收件人不会真正投递。
|
||||
- **服务器部署**：`.env` 默认 `LANQIN_SMTP_HOST=127.0.0.1`，发件交给同容器内 Postfix。
|
||||
- **收件同步**：Postfix/Dovecot 收到 Maildir 后，API 的 Maildir worker 同步到 SQLite 后展示。
|
||||
- **公网收发**：需要正确配置 MX/SPF/DKIM/DMARC，并确认云厂商开放 25/587/993 端口。
|
||||
|
||||
## 要求
|
||||
|
||||
- Go 1.22+
|
||||
- Node.js 20+
|
||||
- Docker & Docker Compose（部署）
|
||||
|
||||
Reference in New Issue
Block a user