Repository Guidelines

项目结构与模块组织

MailHub 是基于 Node.js ESM 的 Docker 化发信控制面板、SMTP Submission 服务和发送 API。服务端代码位于 src/：server.js 负责 HTTP 路由与运行配置，db.js 负责 SQLite 持久化，mailer.js 与 submission.js 处理发信链路，DKIM 与 DNS 能力拆分为独立模块。浏览器资源在 public/，测试在 test/，Docker 与 Postfix 相关文件在 Dockerfile、docker-compose.yml 和 docker/postfix/。运行期数据应保留在已忽略路径，如 data/、.env 和证书私钥文件。

构建、测试与开发命令

npm test：使用 node --test 运行 Node 内置测试套件。
npm run dev：以 NODE_ENV=development 启动 src/server.js。
npm start：启动生产入口。
docker compose up -d --build：构建并启动应用与 Postfix 服务。
docker compose logs -f app postfix：部署或排障时跟踪服务日志。

Node.js 版本需满足 package.json 中的 >=24.0.0。

发布流程

发布前先确认工作区范围，避免把无关变更带上：git status -sb、git log --oneline --decorate -5。提交或部署前必须运行 npm run build、npm test 和 git diff --check；前端构建会更新 public/ 下的静态资源，若 hash 变化应与源码一起提交。

本项目发布需要同步两个 Git 远端：origin 指向 git.ss5.xyz，用于远程服务器拉取部署；github 指向开源仓库，用于同步公开版本。若本地缺少 GitHub remote，先执行一次：

git remote add github git@github.com:chendeben/MailHub.git

确认提交后，先推送部署远端，再同步 GitHub：

git push origin master
git push github master

推送后可用 git status -sb 确认本地分支与 origin/master 对齐；如需确认 GitHub，也可运行 git ls-remote github refs/heads/master 对比本地 git rev-parse HEAD。

生产部署使用远程脚本：

MAILHUB_DEPLOY_REMOTE="root@192.227.215.183" MAILHUB_DEPLOY_DIR="/www/wwwroot/mail.ss5.xyz" npm run deploy:remote

部署脚本会让远程服务器从 git.ss5.xyz 拉取 master 并重建 Docker 服务。部署后需在远程目录检查代码版本、容器健康状态和登录页响应：

cd /www/wwwroot/mail.ss5.xyz
git rev-parse --short HEAD
docker compose ps
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3025/login

预期 mailhub-app 与 mailhub-postfix 均为 healthy，登录页返回 200。发布过程不得覆盖远程 .env、data/、证书私钥或其他运行期数据。

编码风格与命名规范

使用 ES modules，保持文件职责单一、实现直接。默认使用 const，仅在需要重新赋值时使用 let。遵循现有 JavaScript 风格：两空格缩进、保留分号、变量和函数使用描述性 camelCase，浏览器资源文件名使用 kebab-case。注释应简短且有价值，并与周围代码语言保持一致。

测试指南

测试使用 Node 内置 node:test。测试文件放在 test/ 下，并使用 *.test.js 后缀，尽量对应被测模块，例如 test/dkim.test.js。修改数据库迁移、认证边界、DNS 服务商逻辑或邮件签名链路时，应补充相应覆盖。提交 PR 前运行 npm test。

提交与 Pull Request 规范

提交历史使用类似 Conventional Commits 的前缀，如 feat:、fix:、docs:、test:。提交标题应简洁、聚焦单一变更。PR 应包含变更摘要、验证步骤、关联 issue；涉及 UI 或 API 行为变化时，补充截图或请求示例。

安全与配置提示

不要提交 .env、SQLite 数据库、API Token、SMTP 密码或证书私钥。以 .env.example 为起点配置环境，替换默认管理员凭据，设置足够强的 SESSION_SECRET。生产发信前确认 SPF、DKIM、DMARC、PTR 以及云防火墙和系统防火墙规则。

AGENTS.md 3.9 KB Histórico Raw