完善开源体验、交互 Demo 与个人开源集合站

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,21 @@
+name: Bug report
+description: 可复现的问题（安全漏洞请使用私密报告）
+body:
+  - type: input
+    id: version
+    attributes:
+      label: AlertBridge 版本与运行环境
+      placeholder: v0.4.2 / Docker / amd64
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤、预期与实际结果
+      description: 请使用虚构数据，不提交 Token、数据库或私密 URL。
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: 脱敏日志与最小案例

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security report
+    url: https://github.com/xiongwei-git/alertbridge/security/advisories/new
+    about: 请私密报告安全漏洞，不要公开凭据或利用细节。

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,15 @@
+name: Feature proposal
+description: 以实际场景讨论能力与边界
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: 当前无法解决的具体问题
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 建议行为、替代方案与兼容性
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## 解决的问题
+
+<!-- 描述具体触发条件及改变后的行为，关联 Issue。 -->
+
+## 验证
+
+<!-- 填写实际运行的检查、结果和未验证项。界面变更请提供截图。 -->
+
+## 兼容性与运维
+
+<!-- API、数据、部署、凭据是否变化？需要什么迁移/回退？无则写无。 -->

.github/workflows/ci.yml

@@ -27,6 +27,11 @@ jobs:
           go-version: 1.26.5
           cache: true
 
+      - name: Check public website and documentation
+        run: |
+          ./scripts/build-site.sh
+          python3 test/site/test_example.py
+
       - name: Run unit tests
         run: go test ./...
 

.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+name: Publish open source showcase
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Validate and build static showcase
+        run: ./scripts/build-site.sh
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          path: dist-site
+  deploy:
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.gitignore

@@ -13,3 +13,6 @@
 
 PROJECT_BRIEF.md
 PROJECT_MEMORY.md
+
+/dist-site/
+__pycache__/

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## Unreleased — v1.0 candidate
+
+本轮是开源体验里程碑候选，尚未发布 v1.0 镜像。运行服务、v1 API、SQLite 与凭据格式不变，无数据库迁移。
+
+- 新增独立静态官网、交互模拟 Demo、手动 GitHub Pages 发布流程和宝塔静态部署指引。
+- 明确产品价值、适用边界、英文快速介绍与贡献/安全规范。
+- 新增 Python 完整事件调用示例、Dots 使用场景和验收步骤。
+- 保持生产容器、卷、路由、凭据和 Nginx 配置不变。
+
+## v0.4.2
+
+- MCP `list_alerts` 支持 `order=desc` 直接读取最近告警；默认正序和历史游标保持兼容。
+
+## v0.4.1
+
+- 修复 Dots OAuth 授权页 CSP 拦截配置回调的问题。
+
+## v0.4.0
+
+- 新增按路由授权的只读 MCP 工具和 Dots OAuth + PKCE。
+
+更早版本见 [GitHub Releases](https://github.com/xiongwei-git/alertbridge/releases)。

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# 行为准则
+
+我们欢迎不同背景和经验的贡献者。请就问题和证据讨论，尊重他人的时间与隐私，提供建设性反馈。
+
+不接受骚扰、歧视、人身攻击、威胁、恶意泄露个人信息或凭据，以及重复干扰讨论。维护者可编辑或移除违规内容、限制互动或拒绝贡献，并尽可能说明理由。
+
+涉及安全与隐私的报告请使用 [安全政策](SECURITY.md) 中的私密入口；其他行为问题可通过 GitHub 的私密举报功能提交。维护者也受本准则约束。举报内容仅在处理所需范围内分享。

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# 参与 AlertBridge
+
+欢迎修复问题、改善文档和提供可复现的接入案例。先阅读 [README](README.md)、[架构决策](docs/decisions/) 和仓库 [AGENTS.md](AGENTS.md)。
+
+## 开始
+
+1. Fork 并从 `main` 创建功能分支；保持一次 PR 解决一个问题。
+2. Go 版本以 `go.mod` 为准；容器验证需要 Docker Compose。`./scripts/local-demo.sh up` 在本地 18081 端口启动隔离环境。
+3. 先用最小案例说明问题；修复逻辑时补充对应回归测试。文档和静态内容无需重复后端逻辑测试。
+4. 提交 PR 时说明动机、行为变化、兼容性与验证输出。面向用户的变化更新相关文档；公共 API 同步更新 `docs/api.md` 与 `docs/openapi.yaml`。
+
+```sh
+go test ./...
+go vet ./...
+./test/release/run.sh
+./test/e2e/run.sh
+python3 test/site/check.py
+python3 test/site/test_example.py
+```
+
+单进程、SQLite、一个持久 Worker、无 CDN 的服务端后台是有意的取舍。新解析协议、多实例或主动 Agent 触发应先通过 Issue 讨论和 ADR 明确边界。
+
+## 网站
+
+`site/` 是无构建依赖的静态网站与浏览器模拟 Demo，运行 `python3 -m http.server 18083 --directory site` 后访问本机端口。GitHub Pages 与宝塔使用同一份文件。不要在 Demo 中加入生产地址、凭据、分析追踪或真实告警。
+
+## 安全与沟通
+
+安全问题通过 [SECURITY.md](SECURITY.md) 的私密渠道报告。不要附带 Token、数据库或完整私密 URL。遵守 [行为准则](CODE_OF_CONDUCT.md)。贡献使用仓库现有 Apache-2.0 许可；提交即表示你有权按此许可贡献内容。维护由个人利用业余时间进行，不承诺响应 SLA。

README.en.md

@@ -0,0 +1,40 @@
+# AlertBridge
+
+**One small, self-hosted bridge between your services, your notification channels, and your agents.**
+
+AlertBridge receives authenticated events, routes them to Feishu, Telegram, ntfy or TLS SMTP, and records delivery attempts in SQLite. Go, one HTTP process, one database connection and one persistent worker. No Redis, Node.js runtime or external CDN for the admin console.
+
+[中文](README.md) · [Interactive demo source](site/index.html) · [Deployment](docs/deployment.md) · [API](docs/api.md) · [MCP / Dots](docs/mcp.md)
+
+## Why use it?
+
+- Keep channel credentials and retry logic out of every application.
+- Track `firing` / `resolved` incidents and deduplicate repeated events.
+- Inspect queued, sent and failed deliveries; acceptance is not delivery confirmation.
+- Give agents read-only access to permitted routes through MCP, with OAuth + PKCE for Dots.
+
+Use it for personal infrastructure, small teams and single-node operations. It is not a monitoring collector, highly available paging platform, escalation system or autonomous remediation service.
+
+## Try locally
+
+```sh
+git clone https://github.com/xiongwei-git/alertbridge.git
+cd alertbridge
+./scripts/local-demo.sh up
+```
+
+Requires Docker Compose, OpenSSL and curl. The script prints the generated admin password and opens a local-only HTTP environment at `http://127.0.0.1:18081/admin/`. Create a channel, route and client in the console. Never expose this local environment publicly.
+
+For a browser-only simulation, serve `site/` with `python3 -m http.server 18083 --directory site`. This demo uses fictional data and sends no notifications.
+
+Production uses the published GHCR image, HTTPS at your reverse proxy, and loopback-only application exposure. Follow the [deployment guide](docs/deployment.md); back up the database and encryption-key volumes together. Detailed operating documentation is currently in Chinese.
+
+## Integrate
+
+- `POST /api/v1/notifications`: header-only Bearer token, server-bound route and severity, one-off `info` notifications.
+- `POST /api/v1/events`: HMAC-SHA256, replay protection, idempotency and incident lifecycle. See [Python example](examples/python/README.md).
+- `/mcp`: optional, read-only `list_alerts`, `get_alert`, `list_active_incidents`; no acknowledgement, mutation or automatic wake-up.
+
+## Contribute
+
+Read [CONTRIBUTING](CONTRIBUTING.md), [security policy](SECURITY.md), [code of conduct](CODE_OF_CONDUCT.md) and [decisions](docs/decisions/). Licensed under [Apache-2.0](LICENSE). Maintained on a best-effort basis; no availability or support SLA is promised.

README.md

@@ -2,12 +2,39 @@
 
 [![CI](https://github.com/xiongwei-git/alertbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/xiongwei-git/alertbridge/actions/workflows/ci.yml)
 
-AlertBridge 是面向个人、小团队和单节点运维环境的轻量通知网关。外部服务通过简单通知或完整事件 API 提交消息；AlertBridge 负责认证、路由、静默、去重、持久化排队、失败重试和多渠道投递。
+**让服务专注业务，让通知统一到达，让 Agent 按权限读懂告警。**
 
-它采用 Go 单进程、SQLite 和服务端渲染后台，不依赖 Redis、PostgreSQL、Node.js 或 CDN。生产镜像基于 `scratch`；加入官方 MCP SDK 和 Dots OAuth 后，本地 Docker E2E 参考镜像约 21.5 MB、空闲内存约 14 MiB。Compose 默认限制为 128 MiB 内存和 0.5 CPU。
+AlertBridge 是个人、小团队和单节点运维环境的轻量自托管通知网关。业务脚本不再各自维护渠道密钥和重试逻辑：一次接入，统一认证、路由、去重、持久排队与多渠道投递。支持飞书、Telegram、ntfy、TLS SMTP，并提供可选的只读 MCP 与 Dots OAuth。
 
-<img width="1510" height="1290" alt="image" src="https://github.com/user-attachments/assets/5d362c39-163f-460e-8ad2-a907099e3bf9" />
+[English](README.en.md) · [部署指南](docs/deployment.md) · [Dots 实例](docs/dots-example.md) · [Python 接入](examples/python/README.md) · [参与贡献](CONTRIBUTING.md)
 
+## 先理解，再试用
+
+| 你的目标 | 从这里开始 |
+| --- | --- |
+| 不部署，先理解故障到恢复的流程 | [官网与浏览器模拟 Demo 源码](site/index.html)，本地预览见下方 |
+| 体验真实后台、持久化和投递 | `./scripts/local-demo.sh up`，本机 18081 端口 |
+| 部署到自己的服务器 | [Docker + 宝塔指南](docs/deployment.md) |
+| 让 Dots 查询最近告警与活跃故障 | [可验收的 Dots 接入案例](docs/dots-example.md) |
+
+```sh
+# 浏览器演示：仅需 Python 3，无凭据、不连接生产 API
+./scripts/build-site.sh
+python3 -m http.server 18083 --bind 127.0.0.1 --directory dist-site
+# 集合首页 http://127.0.0.1:18083/ ，项目 Demo /alertbridge/
+```
+
+Demo 使用明确标注的虚构数据；真实接收与渠道送达必须在隔离 Docker 环境验证。GitHub Pages 工作流及独立宝塔静态站部署见 [官网部署](docs/showcase-deployment.md)。公开地址将在实际发布验收后添加。
+
+项目采用 Go 单进程、一个 SQLite 连接和一个持久 Worker，不依赖 Redis、PostgreSQL、Node.js 或 CDN。生产镜像基于 `scratch`，Compose 默认限制为 128 MiB 内存和 0.5 CPU。历史本地 E2E 参考镜像约 21.5 MB、空闲内存约 14 MiB；这些不是所有平台的性能保证。
+
+## 为什么保留一个小网关
+
+- **少一份重复逻辑**：把渠道凭据、路由和失败重试从每个业务服务中抽出来。
+- **多一份可查证据**：从接收、去重到投递记录追踪结果；HTTP 接收成功不等于消息送达。
+- **清晰的 Agent 权限**：按路由读取历史、详情和活跃故障，不把告警文本变成执行授权。
+
+适合单节点、小规模自托管；高可用值班、监控采集、升级通知和自动修复需要其他系统或新的架构决策。
 
 ## 当前边界
 
@@ -235,6 +262,12 @@ test/e2e               Docker 端到端测试
 test/release           GHCR/ACR 发布与生产 Compose 契约检查
 ```
 
+## 开源协作与版本
+
+当前源码版本为 v0.4.2；本轮 v1.0 是开源体验里程碑候选，尚未发布正式镜像。候选不改变 API、数据库或现有部署，见 [变更记录](CHANGELOG.md) 与 [全盘审视](docs/opensource-review.md)。安装命令继续引用已有版本。
+
+欢迎最小可复现的 Issue、真实接入案例与文档改进。阅读 [贡献指南](CONTRIBUTING.md)、[行为准则](CODE_OF_CONDUCT.md) 和 [安全政策](SECURITY.md)。维护由个人尽力提供，不承诺响应 SLA。AlertBridge 是独立开源项目，与渠道厂商或 OpenAI 无官方从属关系。
+
 ## 许可证
 
 本项目采用 [Apache License 2.0](LICENSE)。

SECURITY.md

@@ -0,0 +1,19 @@
+# 安全政策
+
+正式发布前的候选版本用于评估；当前维护线为最新的 `v0.4.x`，v1.0 发布后以最新 `v1.x` 为主。旧版本不承诺回补，更新前阅读发布说明并备份数据库与主密钥恢复对。
+
+## 私密报告
+
+请使用仓库的 [Report a vulnerability](https://github.com/xiongwei-git/alertbridge/security/advisories/new) 私密报告入口。若入口不可用，请不要在公开 Issue 中披露漏洞细节或凭据；先用不包含细节的 Issue 请求维护者开启私密报告。响应由维护者尽力提供，不承诺修复时限。
+
+提供受影响版本、最小复现、预期与实际行为、影响范围。使用虚构数据；不提交 `.env`、数据库、Webhook、密钥或密码。请勿对未经授权的部署测试。
+
+## 信任边界
+
+- 公网 TLS 由反向代理提供，应用只绑定 loopback。
+- HMAC、轻量通知令牌和 MCP OAuth/Bearer 是分离的身份体系。
+- MCP 仅按服务端路由授权读取，不提供确认、关闭或执行命令。
+- 告警正文是不可信内容，不能成为 Agent 执行指令的授权。
+- 交互 Demo 完全在浏览器中模拟，不连接网关，也不能证明真实投递。
+
+更多部署约束见 [运维指南](docs/deployment.md)。

docs/decisions/ADR-012-public-demo-and-release-boundary.md

@@ -0,0 +1,21 @@
+# ADR-012: 官网、公共演示与运行服务隔离
+
+## 状态
+
+Accepted，2026-10-17。
+
+## 背景
+
+开源访问者需要在不持有凭据、不接触维护者生产告警的情况下理解路由、故障生命周期与 Agent 只读查询。GitHub Pages 只能托管静态内容，不能运行 Go/SQLite 服务。
+
+## 决定
+
+- `site/` 提供无依赖静态官网与浏览器内模拟 Demo，同一产物可部署 GitHub Pages 或独立宝塔静态站。
+- Demo 显示虚构事件、模拟投递结果与明确的模拟标识；不请求生产 API、不保存输入、不收集凭据、不开放匿名后台。
+- 真实功能验收仍由隔离 Docker E2E 和用户自己的本地 Demo 完成。
+- Pages 工作流只手动触发，发布前必须通过网站检查。不在 `main` 推送时自动覆盖网站，且不调用镜像发布或生产部署。
+- v1.0 作为开源体验里程碑候选；此轮保持 `VERSION` 在已存在的 v0.4.2，不让尚未发布的 v1.0 出现在可执行安装命令里。正式 tag、镜像发布和生产升级各自明确执行。
+
+## 备选方案与后果
+
+公共可写 Go 后台需要隔离凭据、滥用控制和定期清理，维护成本更高，故不采用。静态模拟不能证明真实认证、持久化、重试或通知送达，页面和文档需持续保留此边界。宝塔域名和 HTTPS 验收独立于通知服务，不改现有反向代理、容器、数据库或主密钥。

docs/deployment.md

@@ -360,3 +360,7 @@ curl -fsS http://127.0.0.1:18080/readyz
 | 通知时间比北京时间少 8 小时 | 使用 v0.2.2 或更高版本；确认 `ALERTBRIDGE_DISPLAY_TIMEZONE=Asia/Shanghai`，不要修改服务器系统时钟 |
 
 不要通过关闭既有认证、把令牌放进 URL、使用固定弱密码、把密码放入容器环境变量、放宽出站地址校验或开放应用端口来绕过故障。
+
+## 开源展示站与生产服务隔离
+
+个人开源集合和 AlertBridge 模拟 Demo 是独立静态产物，见 [官网部署](showcase-deployment.md)。它不需要升级运行镜像、复制数据库或暴露后台；域名、根目录和发布流程均与现有服务分离。

docs/dots-example.md

@@ -0,0 +1,31 @@
+# Dots：从“有没有告警”到“查看投递证据”
+
+这是使用现有只读 MCP 的接入案例，不需要 OpenAI API Key。协议配置见 [MCP 指南](mcp.md)。Dots/ChatGPT 的产品入口、权限和可用性取决于实际账号，不承诺所有账号可安装。
+
+## 准备数据与授权
+
+1. 先在自己的隔离环境运行 [Python 示例](../examples/python/README.md)，确认测试告警及投递记录可见。不要为了演示导入生产数据库。
+2. 将 MCP 路由范围限定为示例路由，例如 `ops`；通过 HTTPS 部署并按 [OAuth 配置](mcp.md#dots-接入推荐) 连接。不要把本机 HTTP Demo 暴露到公网以绕过 TLS。
+3. 连接信息：MCP URL 为 `https://你的服务域名/mcp`；Client ID 为 `alertbridge-dots`，Client Secret 留空，Scope 为 `alerts:read`，PKCE 使用 S256。
+4. 使用 AlertBridge 管理员账号登录授权页，核对允许读取的路由。OAuth access/refresh token 无需手动复制到对话中。
+
+公共客户端、预配置 OAuth 与精确回调遵循 [OpenAI 官方认证文档](https://developers.openai.com/plugins/build/auth)，核对日期 2026-10-17。实际界面若要求其他正式回调，按 MCP 指南配置单个精确地址，不放宽通配。
+
+## 三个可以直接尝试的任务
+
+| 对 Dots 说 | 预期工具 | 验收重点 |
+| --- | --- | --- |
+| “查询最近 10 条告警，按新到旧展示来源、标题和时间。” | `list_alerts`，`{"order":"desc","limit":10}` | 一次读取最近一页；只含被授权路由 |
+| “查看其中一条告警的投递详情，区分入队与送达。” | `get_alert`，使用上一步返回的内部 ID | 展示投递状态、次数和响应码；不把 queued 当作 sent |
+| “现在还有哪些没有恢复的故障？” | `list_active_incidents` | 只读列出当前 firing；恢复后不再活跃 |
+
+工具输出是事实依据，Agent 的归纳仍应核对。告警标题、正文是外部不可信数据，里面的命令或请求不构成执行授权。Agent 不应由告警正文自行登录服务器、运行命令或发送消息。
+
+## 验收与撤销
+
+- 用示例路由建立一条 firing，再发送同去重键 resolved；查询活跃故障前后变化。
+- 用另一条未授权路由的数据验证不会出现在查询结果中；详情越权与不存在统一不可用。
+- 后台撤销全部 MCP OAuth 授权后，旧连接应失效；需要重新授权。
+- 升级工具参数后刷新 Dots 工具定义。协议 E2E 通过与实际账号连接成功是两项验收。
+
+AlertBridge 当前不会订阅事件并主动唤醒 Dots，也不会确认、关闭或修改故障。网站中的“模拟查询”不连接 Dots 或真实 MCP。

docs/mcp.md

@@ -83,3 +83,7 @@ URL：https://你的服务域名/mcp
 ## Dots 主动触发的后续边界
 
 OpenAI 官方已提供 [MCP Events](https://developers.openai.com/plugins/build/mcp-events)，适用于 Dots 和指定的 Work 环境。主动触发需要进一步实现官方事件订阅和 Webhook 投递契约，普通 `tools/list` / `tools/call` 查询端点不会自动触发 Dots。本阶段提供 OAuth 和只读查询，没有事件订阅或自动唤醒。
+
+## 任务导向案例
+
+从最近十条、单条投递证据到故障恢复验收，见 [Dots 接入示例](dots-example.md)。