murmansk5000/ironsbot repository overview

⁠IronsBot Docker Image

Docker image for IronsBot⁠, a NoneBot2 / OneBot v11 QQ bot focused on Seer queries and Unraid deployment.

Built-in plugins are discovered from the standard NoneBot TOML manifest. Each plugin exposes PluginMetadata and contributes matchers, command contracts and lifecycle work through PluginContribution; CommandCatalog is the only authority for direct user-command semantics. The temporary private-extension bootstrap only adapts configured external extensions and is not a second plugin registry. Upstream-derived code is retained only where it is still required for data, rendering, or protocol support.

⁠Images

docker.io/murmansk5000/ironsbot:latest
docker.io/murmansk5000/ironsbot:<base-version>.<revision>
docker.io/murmansk5000/ironsbot:sha-xxxxxxx
ghcr.io/murmansk5000/ironsbot:latest
ghcr.io/murmansk5000/ironsbot:<base-version>.<revision>
ghcr.io/murmansk5000/ironsbot:sha-xxxxxxx

阵容 的渲染始终由 IronsBot 主进程完成。公开镜像没有私有协议解析器时会发送标注过的 12 格空白示意图；私有 murmansk5000/ironsbot-private:latest 是一个扩展包镜像，不是 机器人覆盖镜像。公开主镜像在启动前从其中读取受控扩展，并复用主机器人已经登录的无头 米米号。它不启动第二个容器、第二个 API 或第二个无头登录。

私有镜像需要 Docker Hub 拉取凭据。把 DOCKER_REGISTRY_USERNAME 和 DOCKER_REGISTRY_TOKEN 设为容器环境变量，并在 TOML 启用 [operations.private_extensions]。Unraid 的 Repository 和 [operations.docker_update].image 保持公开主镜像。凭据缺失或私有包未安装时，主机器人 仍会启动，阵容查询只显示空白示意图。

容器变量用于已经运行的机器人通过 Docker API 拉取私有扩展包，也可用于 Watchtower 拉取 私有主镜像。当前扩展包方案不要求把 Unraid Repository 改成私有镜像。

latest tracks the main branch of this repository.

⁠Build From Source

Build the Linux image using BuildKit, for example:

docker buildx build --load -t ironsbot:local .

The runtime installation temporarily mounts wheels from the build stage. The wheel archives are not copied into a runtime layer. Dependencies come from the frozen production lockfile; developer tools are excluded. The release workflow measures its published digest and retains image inspection and layer history in an image-size-<commit> artifact. These records distinguish the actual image size from the size of files visible inside a container.

⁠Version Tags And Changelog

This repository keeps Docker latest available, and also publishes extra tags so you can see exactly which build you are running.

• latest: the newest main build, suitable for normal Unraid updates.
• <base-version>.<revision>: IronsBot base version plus this repository's revision.
• sha-xxxxxxx: the exact Git commit used to build the image.

For example, 0.6.0.3 means the image is based on IronsBot 0.6.0 with the 3rd revision after that base version.

Recent changes are tracked in the GitHub commit history and in the Unraid template notes. On Docker Hub, check the tag list for the newest project-version tag and sha-xxxxxxx tag.

⁠Included Plugins

• Seer player, team, pet, mintmark, equipment, type, peak, Autocard, and rank queries.
• Fixed and scheduled messages, fixed images, meeting replies, help, and push controls.
• Bilibili monitoring, activity reminders, open-server notices, and team workflows.
• AI chat, mention protection, intent recognition, and configured template actions.
• Data sync, headless login, startup notices, scheduled restarts, and Docker updates.

Behavior and runtime values belong in a mounted TOML config file. Environment variables are reserved for the config path and secrets. They are intentionally not baked into the image.

⁠Quick Start With Docker Compose

Create a docker-compose.yml and adjust the values for your own environment:

services:
  ironsbot:
    image: murmansk5000/ironsbot:latest
    container_name: ironsbot
    ports:
      - "8085:8080"
    volumes:
      - ./ironsbot-data:/app/data
      - ./ironsbot-config:/config
      - ./ironsbot-logs:/app/logs
      # Optional but recommended: default config checks the image and can
      # restart/update the current container when this socket is mounted.
      # - /var/run/docker.sock:/var/run/docker.sock
    environment:
      APP_CONFIG_PATH: "/config/ironsbot.toml"
      ONEBOT_ACCESS_TOKEN: "change-me"
      # Optional Unraid/deployment overrides for [bot.onebot].
      ONEBOT_ENABLED: "true"
      ONEBOT_SEND_MESSAGES: "true"
      ONEBOT_IDENTITY_VERIFICATION: "false"
      # ONEBOT_TRUSTED_OFFICIAL_BOT_EXAMPLE_BOT: "123456789"
      # Optional QQ Official AppSecret. The numeric suffix is the public app_id
      # declared under [bot.qq_official.accounts.<alias>].
      # APP_SECRET_10001: "change-me"
    restart: always

  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    mac_address: 02:42:ac:11:00:02
    ports:
      - "6099:6099"
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
    environment:
      NAPCAT_UID: "1000"
      NAPCAT_GID: "1000"
      NAPCAT_WEB_TOKEN: "change-me"
      NAPCAT_REVERSE_WS_POST: "ws://ironsbot:8080/onebot/v11/ws"
      NAPCAT_REVERSE_WS_TOKEN: "change-me"
    restart: always

Before starting the container, create ./ironsbot-config/ironsbot.toml from config.example.toml⁠ and set [bot].superusers. IronsBot strictly validates this file at startup. It never creates or rewrites the file.

On Windows Docker Desktop, the left side of the volume is a Windows directory. Choose any writable directory on any drive. For example:

$IRONSBOT_HOME = "D:\DockerData\ironsbot"
New-Item -ItemType Directory -Force `
  "$IRONSBOT_HOME\config", "$IRONSBOT_HOME\data", "$IRONSBOT_HOME\logs"
docker run --name ironsbot `
  -p 8085:8080 `
  -v "${IRONSBOT_HOME}\config:/config" `
  -v "${IRONSBOT_HOME}\data:/app/data" `
  -v "${IRONSBOT_HOME}\logs:/app/logs" `
  -e APP_CONFIG_PATH=/config/ironsbot.toml `
  -e ONEBOT_ACCESS_TOKEN=change-me `
  murmansk5000/ironsbot:latest

In this example, /config/ironsbot.toml inside the container is D:\DockerData\ironsbot\config\ironsbot.toml on Windows.

Optional Docker image check/update: superusers can send /重启机器人 for the restart flow. /更新镜像 and /更新Docker are read-only checks first; a new image requires an explicit yes/y confirmation before IronsBot starts a one-shot Watchtower updater and keeps the old container from starting the bot. By default config.example.toml checks the target image on startup and before a manual restart. The recreated container verifies that it is running the expected image before it starts NoneBot, data sync, or startup notifications. If Watchtower fails, the old container stays in the handoff state and its Watchtower container is kept for log inspection. When the image is already current and Docker socket is mounted, /重启机器人 restarts the current Docker container through the Docker API instead of relying on container restart policy. This requires mounting the Docker Engine socket into the IronsBot container, for example on Unraid/Linux:

/var/run/docker.sock:/var/run/docker.sock

Without that socket mount, image checks are skipped and the bot continues to run normally; manual restart falls back to process restart.

The example TOML includes explicit switches for checking the image before other startup tasks such as data sync and before manual restart commands:

[operations.docker_update]
check_on_startup = true
watchtower_docker_api_version = "1.40"

Both switches are enabled by default so operators can see where to disable them. Set one or both to false when running directly from source on Windows/macOS/Linux without Docker socket access, or when you prefer manual image updates. Keep watchtower_docker_api_version = "1.40" on recent Unraid/Docker Engine versions if Watchtower reports that client API version 1.25 is too old.

Push notices are split into separate subscriptions, such as bot startup, Docker image check, startup data sync, AI chat errors, Bilibili login notices, headless Seer notices, render crash notices, red packet notices, Bilibili pushes, activity reminders, and open-server pushes. Private users can send TD; group owners or admins can send TD in a group to unsubscribe from each push category independently.

User command limits are configured under [messaging.command_cooldown]. The key is the QQ user plus a stable semantic command ID, so aliases and different parameters of the same operation share exact sliding-window quotas while unrelated operations remain independent. Command limits are disabled by default; set enabled = true to use the built-in three requests per 60 seconds and five per 300 seconds windows. Group output limits are also disabled by default and are configured under [messaging.outbound_rate_limit] as multiple sliding windows once enabled. Normal replies are suppressed immediately after the quota is reached; proactive pushes may wait in a short per-group FIFO queue. Private messages and groups enabled for admin_notice are not counted.

The bot needs a OneBot v11 client such as NapCat. If NapCat and IronsBot are in the same Compose network, configure NapCat reverse WebSocket to:

ws://ironsbot:8080/onebot/v11/ws

If NapCat is created separately in Unraid bridge mode, use the Unraid host IP and mapped port instead:

ws://UNRAID_SERVER_IP:8085/onebot/v11/ws

The reverse WebSocket token must match ONEBOT_ACCESS_TOKEN.

Multiple NapCat / OneBot v11 clients may connect to the same IronsBot WebSocket endpoint. Configure [messaging.bot_routing] in ironsbot.toml when proactive messages should use different bot accounts for different groups or users:

[messaging.bot_routing]
enabled = true
default_bot = "main_bot"

[messaging.bot_routing.bot_aliases]
main_bot = 111111111
backup_bot = 222222222

[messaging.bot_routing.groups]
group_a = "main_bot"
group_b = "backup_bot"

[messaging.bot_routing.users]
owner = "main_bot"
user_a = "backup_bot"

Group and user aliases come from [identities.groups] and [identities.users]; numeric IDs are also accepted. Replies to incoming commands keep using the bot that received the event. Bilibili, activity, scheduled-message, server-status, startup, and other proactive deliveries use the configured route. Routing does not filter incoming events, so avoid placing multiple responding bots in the same group unless you separately control which events each OneBot client forwards.

⁠Configuration

Behavior config is file-based:

• Create ironsbot.toml from config.example.toml, then mount its directory to /config.
• Set APP_CONFIG_PATH=/config/ironsbot.toml.
• Use config.example.toml for all fields, defaults, English descriptions, Chinese descriptions, and examples.

If APP_CONFIG_PATH is not set, IronsBot falls back to config/ironsbot.toml in the current working directory. Missing config files cause startup to fail. IronsBot never mutates the TOML file. Relative data/ and logs/ paths live under the current working directory.

APP_CONFIG_PATH=/config/ironsbot.toml
ONEBOT_ACCESS_TOKEN=change-me
ONEBOT_ENABLED=true
ONEBOT_SEND_MESSAGES=true
ONEBOT_IDENTITY_VERIFICATION=false
ONEBOT_TRUSTED_OFFICIAL_BOT_EXAMPLE_BOT=
APP_SECRET_10001=
AI_KEY_DEEPSEEK=
# Add one variable for each additional [ai.providers.<alias>].
# AI_KEY_FUMIN=
# AI_KEY_NOMISS=
# Add the plain password for each [[seer.player_accounts]] player ID that logs in.
# IronsBot converts it to MD5 in memory.
SEER_PASSWORD_123456789=
SEER_PASSWORD_987654321=
SENDPIC_CNB_TOKEN=
GITHUB_WORKFLOW_TOKEN=
DOCKER_REGISTRY_USERNAME=
DOCKER_REGISTRY_TOKEN=

QQ Official custom command keyboards are a TOML capability, not an environment variable. Keep bot.qq_official.accounts.<alias>.custom_keyboards = false unless Tencent has enabled the invite-only custom-button permission for that AppID. Account startup policy is also TOML: use required = true only when that account must become READY/RESUMED for the container to be considered started, and adjust bot.qq_official.startup_timeout_seconds when the default 15 seconds is not suitable. Neither setting contains a secret or belongs in Unraid variables.

Published Docker images include the QQ Official runtime together with the OneBot/NapCat runtime. Complete official credentials select QQ Official as the only outbound transport and force NapCat silent; failures never fall back to NapCat. Without official credentials, bot.onebot.send_messages controls OneBot outbound. A source checkout uses uv sync --extra qq-official followed by uv run --no-sync python -m ironsbot. A custom OneBot-only image may explicitly set --build-arg IRONSBOT_RUNTIME_EXTRA= to omit the optional SDK dependency.

Validate a mounted configuration without starting adapters, schedulers, databases, or network clients:

docker run --rm --entrypoint python \
  -v /mnt/user/appdata/ironsbot/config:/config:ro \
  --env-file /path/to/a/temporary-validation.env \
  murmansk5000/ironsbot:<exact-tag> \
  -m ironsbot.config_check --no-dotenv --config /config/ironsbot.toml

Use a copied TOML and a temporary env file for migration checks. The command prints only transport selection, configured account aliases, and AI provider aliases/model counts; it never prints credential values or transport IDs.

Set superusers, listen address, port, command prefixes, and logging under [bot] in TOML. When file logging is enabled, the default logs rotate at local midnight, keep 30 days, and are not compressed; adjust [bot.logging] if disk space requires a different policy.

Feature names are used in [features.group_policy] and [features.user_policy]:

Message actions may also use feature names such as web_activity_link, web_activity_push, or seerinfo.

[identities.groups]
admin = 123456789
main = 987654321

[identities.users]
owner = 1234567890

[features]
superuser_bypass = true

[features.group_policy]
admin = ["admin_notice"]
main = ["seer", "meeting", "web_activity_link", "bili_query", "bili_push", "ai_chat", "ai_intent", "ai_intent_team_recommend", "fire_manual_ad", "ai_intent_fire_manual"]

[features.user_policy]
owner = ["all"]

[bilibili.accounts.seer]
uid = 1310714247

[bilibili.push]
accounts = ["seer"]
mode = "link"
modes = { seer = "full" }

[bilibili.push.groups.main]
accounts = []
mode = "link"

# Group owners/admins can inspect and override one subscribed account at runtime:
# B站账号
# B站推送模式 seer 链接
# Public Bilibili names and numeric UIDs are also accepted.

⁠Behavior Config Validation

Behavior settings belong in /config/ironsbot.toml. The current .env and Unraid template only contain deployment settings and secrets, so behavior upgrades do not require adding behavior fields to the container template. Configuration validates documented fields, references, and values at startup and reports the TOML path for invalid entries. Use config.example.toml⁠ as the authoritative configuration shape.

⁠Team Resource Subscription

If you use this Docker image for a Seer team/guild QQ group, you can subscribe that group to one or more teams. The same subscription lets members query those teams with a short command and lets the bot remind configured users when team resources are low.

Example behavior:

User sends: 战队
Bot replies: team info for each configured team ID

This is the same kind of output as the built-in 战队<team_id> query, but the group member does not need to remember the team IDs.

Enable the feature and default reminder settings in ironsbot.toml:

[identities.groups]
example = 987654321

[identities.users]
owner = 1234567890

[features]

[features.group_policy]
example = ["team_resource_subscription"]

[seer.team_resource]
times = ["23:00"]
commands = ["战队"]
default_threshold = 1000
default_at_users = ["owner"]
query_timeout_seconds = 20
resource_line = "查到了战队 {team_name}（{team_id}）资源是 {resource}，低于阈值 {threshold}。"
resource_message = "出来买资源，别逼我求你😡"

Then group owners/admins manage subscriptions in QQ:

订阅战队123456
订阅战队123456 1000 @提醒人
战队订阅
取消订阅战队123456

Keep real QQ group IDs in a mounted config file outside the repository, such as an Unraid appdata directory. Runtime team subscriptions are stored in the shared [paths].qq_state database; do not commit that database to GitHub.

⁠OneBot 自发指令（Docker / Unraid）

在容器挂载的 TOML 配置中按需添加，不新增 Unraid 环境变量：

[bot.onebot.self_commands]
enabled = false
prefixes = ["演示 ", "示范 "]

默认关闭，未使用者无需迁移。开启时同时在 NapCat 打开 reportSelfMessage， 使用机器人 QQ 本人在群内发送 演示 帮助；数字选择和退出也写成 演示 1、演示 0。前缀末尾空格有意义，多个前缀按最长匹配。 该 QQ 只使用已有 TOML 权限，不自动变为超级管理员或管理通知收件人。 官方凭据接管或 OneBot 发送关闭时始终静默，不回退到 NapCat。

从原版迁移：[runtime.self_commands] 改成 [bot.onebot.self_commands]， prefix 改成 prefixes，删除旧 superuser；不保留旧字段兼容入口。 当前消息含 @全体成员 时不响应，引用正文中的提及除外。

⁠Unraid

This repository includes a Community Applications-ready Unraid template:

• IronsBot template: templates/ironsbot.xml
• CA profile: ca_profile.xml

Template URLs:

https://raw.githubusercontent.com/Murmansk5000/IronsBot/main/templates/ironsbot.xml

The Unraid template exposes a minimal variable set and mounts a config directory. Put behavior and runtime settings in /config/ironsbot.toml; keep only APP_CONFIG_PATH and secret values as environment variables.

⁠Privacy Notes

Do not put private QQ IDs, group IDs, team IDs, meeting links, meeting numbers, account passwords, or tokens into files committed to GitHub.

Use one of these instead:

• a mounted TOML config outside the repository, such as /config/ironsbot.toml
• Docker Compose environment variables for secrets and credentials
• Unraid container variables for secrets and credentials
• ignored local files such as .env.prod
• Docker / Unraid secret management where available

If a token or meeting link has ever been pushed to a public repository, treat it as exposed and rotate it.

⁠Links

• Fork repository: Murmansk5000/IronsBot⁠
• Upstream repository: Nattsu39/IronsBot⁠
• Credits and data-tool upstreams: README acknowledgements⁠
• Docker Hub image: murmansk5000/ironsbot⁠
• GHCR image: ghcr.io/murmansk5000/ironsbot

⁠License

This image follows the licensing terms of the repository. See LICENSING.md in the source repository for details.