maxionice/maxionice-discord-bot

为单个双语 Discord 服务器提供的生产级社区基础设施。
在单个 TypeScript 服务中集成 Tickets、临时语音房间、自助角色和防御性自动化功能。

加入社区  ·  快速开始  ·  安全模型  ·  运维

## 运行内容 | 系统 | 功能 | | --- | --- | | **服务器设置** | 同步完整的 DE/EN 结构、角色、权限、频道顺序和持久化控制面板。 | | **成员引导** | 使用 Discord 原生问题以及带有品牌标识的加入指南，用于设置语言、兴趣和可选的更新提醒。 | | **私人支持** | 提供常规、技术、Arma Reforger 和 FiveM Tickets，支持认领、私人语音、关闭和记录流程。 | | **动态语音** | 加入即创建的房间，房主可控制锁定、解锁、重命名、用户限制、认领和删除。 | | **社区角色** | 为德语、英语、游戏、开发、AI 工具、Arma Reforger、FiveM 和更新通知提供自助角色。 | | **GitHub 更新** | 检测新的仓库、推送和发布，然后根据仓库主题或发布标签进行路由。 | | **安全** | 阻止外部 Discord 邀请，并添加蜜罐、垃圾信息遏制和审计日志反核武（anti-nuke）阈值。 | | **运维** | SQLite 持久化、幂等启动、Docker 加固、日志轮换和 GitHub Actions 验证。 | ## 服务器蓝图 ``` START HERE DE / EN COMMUNITY |- join guide + rules |- language-gated chats |- announcements |- introductions |- language roles `- member showcases `- private ticket panel DEVELOPMENT MODDING + GAMING |- dev talk |- Arma Reforger releases |- project updates |- FiveM releases |- coding help forum `- gaming + LFG |- project forum `- resources DYNAMIC VOICE STAFF + SECURITY |- DE / EN / Gaming |- ticket channels |- owner control panel |- support voice rooms `- automatic cleanup |- mod log + transcripts `- honeypot + anti-nuke ``` 该设置是刻意设计为幂等的：再次运行 `/setup` 会修复名称、层级、权限、排序和面板，而不会复制服务器内容。 ## 交互流程 ``` flowchart LR Member[Community member] --> Roles[Language and interest roles] Member --> Ticket[Private support ticket] Member --> Voice[Join-to-create voice] Ticket --> Claim[Staff claim] Ticket --> SupportVoice[Private support room] Ticket --> Transcript[Transcript in mod-log] Voice --> Controls[Lock / limit / rename / delete] Security[Message + audit events] --> Containment[Ban or quarantine] Containment --> Alert[Staff alert + persistent stats] GitHub[GitHub repositories] --> Router[Topic + release-tag router] Router --> Releases[Arma / FiveM / Tech channels] ``` ## 快速开始 ### 1. Discord 应用 在 Discord Developer Portal 中创建一个 bot 并启用： - **Server Members Intent** - **Message Content Intent** - `bot` 和 `applications.commands` OAuth2 scopes 为了完成全自动设置，bot 需要具有管理频道、角色、消息、成员和审计日志的权限。其托管角色的位置必须保持在它预期分配、隔离或管理的所有角色之上。 ### 2. 配置 ``` git clone https://github.com/maxionice/maxionice-discord-bot.git cd maxionice-discord-bot cp .env.example .env ``` 在 `.env` 中设置所需的值： | 变量 | 用途 | 默认值 | | --- | --- | --- | | `DISCORD_TOKEN` | 来自 Developer Portal 的 bot token | 必需 | | `CLIENT_ID` | Discord 应用 ID | 必需 | | `GUILD_ID` | 目标服务器 ID | 项目服务器 | | `AUTO_SETUP` | 在启动时同步服务器 | `true` | | `DATABASE_PATH` | SQLite 数据库位置 | `./data/maxionice.sqlite` | | `SECURITY_BAN_BOTS` | 在触发遏制机制后封禁恶意 bot | `true` | | `GITHUB_USER` | 用于监控项目和发布的公开 GitHub 账户 | `maxionice` | | `GITHUB_POLL_INTERVAL_MS` | 轮询间隔（毫秒） | `300000` | | `GITHUB_TOKEN` | 用于提高 GitHub API 限制的可选 token | 未设置 | 切勿提交 `.env`、Discord token 或生产数据库文件。 ### 3. 在本地运行 ``` npm ci npm run typecheck npm test npm run build npm start ``` 应用命令会在启动时注册。也可以使用 `npm run register` 作为单独的注册步骤。 ## 命令 | 命令 | 权限 | 结果 | | --- | --- | --- | | `/status` | 成员 | 返回 gateway 延迟和活跃的服务模块。 | | `/guide` | 成员 | 再次显示个性化的双语欢迎指南。 | | `/setup` | 管理员 | 同步完整的服务器结构和所有持久化面板。 | 成员日常使用的所有功能都由按钮或模态驱动。加入指南会立即询问语言、兴趣和可选通知；`/guide` 仅作为重播操作。 ## GitHub 路由 监控器在首次运行时会建立一个安静的基线，然后仅播报未来新增的仓库、推送和发布。路由使用 GitHub 仓库主题，并可将发布标签作为显式覆盖： | 目标 | 仓库主题或发布标签提示 | | --- | --- | | `#arma-releases` | `arma-reforger`, `arma-mod`, `reforger`, `enfusion` | | `#fivem-releases` | `fivem`, `cfx` | | `#project-updates` | 涵盖两个生态系统的所有其他技术项目及仓库 | 对于其他有歧义的仓库，请在发布标签前加上 `arma-` 或 `fivem-` 前缀。只有选择了 `Updates` 角色的成员才会收到 ping 提醒。 ## 安全模型 bot 将 Discord 权限视为主要边界，并将自动化视为快速遏制层。 1. **预防：** 私有分类权限覆盖、只读入口频道和受限的隔离角色。 2. **检测：** 外部 Discord 邀请、蜜罐消息、提及洪水、重复 payload、跨频道爆发和破坏性审计日志事件。 3. **遏制：** 删除触发消息，移除危险的可编辑角色，隔离并超时某个成员，或封禁恶意 bot。 4. **记录：** 将员工警报、Ticket 记录和持久化的安全计数器写入 SQLite 和 Discord。 反核武（anti-nuke）阈值会对 20 秒内的 3 起破坏性角色或频道事件做出反应。服务器所有者和 bot 本身被排除在自动遏制之外。Discord 还会阻止任何 bot 管理最高角色等于或高于自身的账户。 ## 运维 ### Docker Compose ``` docker compose up -d --build docker compose logs -f bot ``` 生产容器以非特权用户 `node` 运行，具有只读根文件系统，丢弃了所有 Linux capabilities，启用了 `no-new-privileges`、受限的临时文件系统和有界的 JSON 日志。只有 `./data` 是可写且持久化的。 ### 服务检查 ``` docker compose ps docker compose logs --since=10m bot npm run typecheck && npm test && npm run build ``` CI 会在每次推送和 pull request 时运行类型检查、安全性和持久性测试，以及完整的生产构建。 交互式面板具有会话感知能力：优雅停止会在 bot 下线前移除它们，并且在启动时发布一组全新的面板，且不会带有 Discord 永久的 `edited` 标记。如果主机瞬间断电或断网，在 bot 重新连接之前无法更改 Discord；下一次启动仍会替换任何陈旧的面板。 ## 项目结构 ``` src/ |- setup.ts Server structure, roles, permissions and panels |- tickets.ts Ticket lifecycle, support voice and transcripts |- voice.ts Temporary voice lifecycle and owner controls |- security.ts Honeypot, spam protection and anti-nuke logic |- github.ts Persistent GitHub watcher and topic-based routing |- panels.ts Clean persistent-panel publishing |- welcome.ts Join banner and bilingual onboarding guide |- database.ts SQLite persistence `- index.ts Discord event and interaction routing test/ Security and persistence tests compose.yaml Hardened production runtime Dockerfile Reproducible multi-stage image ``` ### 一个受信任的链接 **[MrFrostDev](https://github.com/MrFrostDev)** 是我最好的朋友，也是唯一一个在这里永远拥有永久位置的外部人员。他是一位才华横溢的开发者，背后有许多激动人心的项目。对于合适的委托，客户也可以将 MrFrostDev 和我作为一个开发双人组一起预订。 - GitHub: [github.com/MrFrostDev](https://github.com/MrFrostDev) - Discord 社区: [discord.gg/FQQyMfj3Rp](https://discord.gg/FQQyMfj3Rp) - 联合项目咨询：请在 Discord 上联系 `.maxionice` 或发送电子邮件至 [maxionice@protonmail.com](mailto:maxionice@protonmail.com) ## 许可证 基于 [MIT License](LICENSE) 发布。

标签：Discord 机器人, MITM代理, TypeScript, 动态语音, 安全插件, 工单系统, 社区管理, 网络研究, 网络调试, 自动化, 请求拦截, 防御机制