Smail/docs/插件构建与配置.md

插件构建与配置

配置入口

在“设置 → 配置管理 → 插件配置”中选择三级菜单：

• 垃圾邮件拦截
• Telegram 推送
• 微信推送

每次只显示所选插件的字段。切换页面前会提示未保存的编辑内容；三个插件仍共用后端插件配置分区，保存时保留其余插件、内部字段和权限。服务器存在候选配置时，页面会提示候选涉及哪些插件，应用时整个候选一起生效。

Windows 开发构建

先安装 frontend 和 plugins/pmail_telegram_push 的前端依赖，然后在项目根目录运行：

powershell -NoProfile -ExecutionPolicy Bypass -File deploy/build.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service backend

修改后端或重新编译正在运行的插件前，先停止对应开发服务。-SkipFrontend 只跳过主前端，三个插件始终随开发构建编译，Telegram 的嵌入页面也会重新生成。

• 主前端：out/frontend
• 后端及管理工具：out/backend
• 三个插件：out/plugins/spam_block.exe、out/plugins/pmail_telegram_push.exe、out/plugins/wechat_push.exe
• 开发服务工作目录：out，保证相对路径 plugins 指向实际插件产物
• SMAIL_ROOT 仍固定到项目根目录，现有账号、邮件数据库和运行配置保持在根目录 config，不能复制一份到 out/config

跨平台构建与发布

make build

构建依赖顺序为：主前端 → 后端、三个插件 → 发布目录。使用并行构建时也不会在产物尚未生成前打包。

插件统一构建入口：

node deploy/build-plugins.mjs --target=linux_amd64
node deploy/build-plugins.mjs --target=windows_amd64
node deploy/build-plugins.mjs --all

支持 Linux、Windows、macOS 的 amd64 和 arm64。插件编译中间产物位于 out/plugins/<平台>_<架构>，发布目录位于 out/package/Smail_<系统>_<架构>/smail/。系统名使用 linux、windows、darwin。压缩包输出到 out/release/，例如 Smail_linux_amd64.tar.gz、Smail_windows_amd64.zip。Windows 使用 ZIP，其余平台使用 TAR.GZ。

每个压缩包解压后直接得到以下结构，Windows 的三个程序带 .exe 后缀：

smail/
├── smail
├── smail-admin
├── smail-config
├── config/
├── data/
├── ssl/
└── log/

网页和三个插件的可执行文件内嵌于主程序。插件运行时仍是独立进程，原有启停配置和进程隔离检查不变。包内四个目录为空，不携带本机配置、数据库、密钥、证书、部署或续期脚本；首次运行通过项目初始化流程生成配置。管理员恢复工具和配置迁移工具均为编译后的程序。

Makefile 和 GitHub 发布工作流统一调用 node deploy/package.mjs。已有编译产物时可附加平台参数单独打包，例如 node deploy/package.mjs linux_amd64。Windows 主机生成 Linux/macOS 压缩包时自动使用 Git for Windows 附带的 GNU tar，以写入 Unix 可执行权限，也可通过环境变量 SMAIL_TAR 指定其他 GNU tar 路径；Windows ZIP 使用系统 tar，Linux/macOS 主机分别使用 tar 和 zip。上述工具仅在构建机器使用，部署服务器不需要构建或部署脚本。

打包先检查三个程序，再从全新目录生成发布包。相同名字的旧目录、压缩包和回执移入 out/build-history/release-*/ 保留，旧版平铺产物不参与打包。校验回执在 out/release-receipts/Smail_<系统>_<架构>.json，包含程序和压缩包的 SHA-256，不进入发布包。

编译成功不代表第三方服务已配置、推送已送达或生产平台隔离验收完成。Windows 生产模式现有的插件隔离限制仍然保留，不会因打包而绕过。