notify 提供统一的通知发送入口，首版已实现 email 渠道，并预留了多渠道扩展能力。项目同时包含：

• 业务发送 API
• 管理后台
• SQLite 配置存储
• Docker Compose 一键启动
• CI / Release 自动发布

• 统一发送入口：POST /api/v1/notifications/send
• 当前已实现 email 渠道
• 支持多个 SMTP 账号
• 支持默认账号和显式 account_id
• Bearer Token 鉴权
• 内置 /admin 管理后台
• SQLite 持久化通知账号配置

• cmd/notify：服务入口
• internal/httpapi：Gin 路由、鉴权、中间件、HTTP Handler
• internal/notify：通知抽象、channel 分发、email 发送
• internal/admin：后台管理服务逻辑
• internal/store/sqlite：SQLite 仓储实现
• web/admin：React + Vite 管理后台
• api_test：HTTP 接口调试示例

1. 复制环境变量模板：

cp .env.example .env

2. 至少配置以下变量：

• API_BEARER_TOKEN
• ADMIN_API_TOKEN

3. 如果希望启动时自动初始化一条默认 SMTP 账号，再补充：

• BOOTSTRAP_EMAIL_HOST
• BOOTSTRAP_EMAIL_PORT
• BOOTSTRAP_EMAIL_USERNAME
• BOOTSTRAP_EMAIL_PASSWORD
• BOOTSTRAP_EMAIL_FROM_EMAIL
• BOOTSTRAP_EMAIL_FROM_NAME
• BOOTSTRAP_EMAIL_ENCRYPTION

4. 本地启动：

make run

默认服务地址：

• API: http://localhost:8080
• Admin: http://localhost:8080/admin

后端：

make run

后台前端开发模式：

make admin-dev

常用命令：

• make fmt：格式化 Go 代码
• make tidy：整理 Go 依赖
• make test：运行 Go 测试
• make build：构建后端二进制到 bin/notify
• make admin-install：安装管理后台依赖
• make admin-test：运行管理后台测试
• make admin-build：构建管理后台静态资源
• make docker-build：构建 Docker 镜像
• make docker-up：通过 Docker Compose 启动
• make docker-down：停止 Docker Compose
• make docker-logs：查看容器日志

接口调试示例见 api_test。

基础配置：

• APP_PORT：服务端口，默认 8080
• API_BEARER_TOKEN：业务 API 鉴权 token，必填
• ADMIN_API_TOKEN：管理后台和管理 API 鉴权 token，必填
• DATABASE_URL：SQLite DSN，优先级高于 SQLITE_PATH
• SQLITE_PATH：SQLite 文件路径，默认 ./notify.db

可选启动初始化：

• BOOTSTRAP_EMAIL_ACCOUNT_ID：默认 email_default
• BOOTSTRAP_EMAIL_ACCOUNT_NAME：默认 Default Email Account
• BOOTSTRAP_EMAIL_HOST
• BOOTSTRAP_EMAIL_PORT：默认 587
• BOOTSTRAP_EMAIL_USERNAME
• BOOTSTRAP_EMAIL_PASSWORD
• BOOTSTRAP_EMAIL_FROM_EMAIL
• BOOTSTRAP_EMAIL_FROM_NAME
• BOOTSTRAP_EMAIL_ENCRYPTION：支持 none|ssl|starttls，默认 starttls

只要设置了 BOOTSTRAP_EMAIL_HOST，服务启动时就会把这套 SMTP 账号写入数据库并设为默认账号。

环境变量模板见 .env.example。

后台入口：

• 页面：/admin
• API：/admin/api/v1

当前支持：

• 查看邮件账号列表
• 新建和编辑 SMTP 账号
• 启用和停用账号
• 切换默认账号
• 测试发信
• 生成调用业务 API 的 cURL 示例

生产环境部署前，先执行：

make admin-install
make admin-build

项目内置 docker-compose.yml 和 Dockerfile。

启动方式：

docker compose up -d --build

或者：

make docker-up

说明：

• 服务监听宿主机 ${APP_PORT:-8080}
• SQLite 数据库存放在 Compose 命名卷 notify_data
• 管理后台构建产物会在镜像构建阶段自动打包

发送通知：

curl -X POST http://localhost:8080/api/v1/notifications/send \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "email",
    "metadata": {
      "biz": "signup",
      "idempotency_key": "abc-123"
    },
    "payload": {
      "to": ["[email protected]"],
      "subject": "Welcome",
      "text": "hello from notify",
      "html": "<p>hello from notify</p>"
    }
  }'

指定账号发送：

curl -X POST http://localhost:8080/api/v1/notifications/send \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "email",
    "account_id": "email_default",
    "payload": {
      "to": ["[email protected]"],
      "subject": "Welcome",
      "text": "hello from notify"
    }
  }'

健康检查：

curl http://localhost:8080/healthz

后台 token 校验：

curl http://localhost:8080/admin/api/v1/auth/verify \
  -H 'Authorization: Bearer admin-change-me'

更多调试请求见 api_test。

项目已内置 GitHub Actions 和 GoReleaser：

• .github/workflows/ci.yml
  • 所有分支 push / pull_request 自动执行 Go 测试、后台测试、后台构建和 Docker 镜像构建校验
  • 不发布任何二进制和镜像
• .github/workflows/release.yml
  • 推送 v* tag 时自动创建 GitHub Release
  • 自动发布 GoReleaser 打包产物
  • 自动发布 GHCR Docker 镜像，并打上 vX.Y.Z、X.Y、X、latest
• .goreleaser.yaml
  • 定义二进制打包和 release 行为

发布方式：

git tag v0.1.0
git push origin v0.1.0

说明：

• 只有推送 v* tag 才会真正发布 Release 和 Docker 镜像
• 新仓库使用前，建议在 GitHub 仓库 Settings -> Actions -> General 中将 Workflow permissions 设为 Read and write permissions
• 当前 GoReleaser 二进制产物默认只打 linux/amd64
• Docker 镜像当前只发布 linux/amd64
• 原因是项目依赖 sqlite3 CGO，当前 Docker 构建链路下 linux/arm64 交叉编译不稳定

服务启动时会自动初始化 notification_accounts 表，用于存储通知渠道账号配置。

当前 config_json 内保存 Email SMTP 配置，后续新增其他渠道时可以沿用同一模型扩展。