AstrBridge 是一个连接 AstrBot 和 Velocity 的远程管理桥接插件。它可以让 AstrBot 通过 Velocity 执行管理命令，也可以把命令转发到 Docker 中运行的 Minecraft 子服容器。
- AstrBot 通过 TCP 连接 AstrBridge，不依赖原生 RCON。
- 不指定子服时，命令在 Velocity 代理上执行。
- 指定子服时，Velocity 会转发给 Python backend，再通过
docker exec在目标容器内执行。 - 支持 Docker 子服自动发现，并能自动补全缺失的
server.*配置。 - 支持命令白名单，避免随意开放高风险命令。
典型调用链：
AstrBot
-> Velocity 上的 AstrBridge 插件
-> AstrBridge Python backend
-> docker exec 到指定 Minecraft 容器
Velocity 所在机器需要安装：
java -version
python3 --version
docker --version
docker ps运行 Velocity 的系统用户必须有权限执行 docker ps 和 docker exec。
构建插件：
gradle build将生成的 jar 放入 Velocity 的 plugins 目录：
cp build/libs/AstrBridge-*.jar /path/to/velocity/plugins/启动一次 Velocity，让插件生成数据目录：
/path/to/velocity/plugins/astrbridge/
主要配置文件：
/path/to/velocity/plugins/astrbridge/astrbridge.conf
请先修改默认 token：
bridge.host=127.0.0.1
bridge.port=25580
bridge.token=replace_with_a_strong_random_token
bridge.read-timeout-ms=15000
bridge.max-clients=4
bridge.default-server=
backend.host=127.0.0.1
backend.port=25590
backend.token=replace_with_another_strong_random_token
backend.auto-start=true
backend.python=python3
backend.startup-timeout-ms=30000
security.enable-ip-whitelist=false
security.whitelist=127.0.0.1,::1说明：
bridge.host/bridge.port：AstrBot 连接 AstrBridge 的地址。bridge.token：AstrBot 侧rcon_password填这个值。backend.host/backend.port：Velocity 插件连接 Python backend 的地址。backend.token：Velocity 和 Python backend 内部通信使用。backend.auto-start=true：Velocity 启动时自动拉起 Python backend。
如果 AstrBot 不在 Velocity 同一台机器上，才需要把 bridge.host 改成 0.0.0.0，并用防火墙只放行 AstrBot 所在 IP。
AstrBridge 默认启用 Docker 自动发现：
backend.auto-discover-servers=true
backend.auto-discover-write=true
backend.auto-discover-default-shell=mc-console
backend.auto-discover-default-allowed-prefixes=list,say,lp,whitelist启动时插件会读取 Velocity 已注册的子服，然后运行 docker ps 匹配容器。匹配顺序：
- 容器 label：
astrbridge.server=<Velocity 子服名> - 容器名匹配，例如
survival或minecraft-survival - Docker 端口映射匹配 Velocity 子服端口
推荐给容器添加 label，这是最稳定的识别方式：
services:
survival:
image: your-minecraft-image
labels:
astrbridge.server: survival匹配成功后，插件只会追加缺失的 server.* 配置，不会覆盖已有配置。
也可以手动配置：
server.survival.container=minecraft-survival
server.survival.shell=mc-console
server.survival.allowed-prefixes=list,say,lp,whitelist
server.creative.container=minecraft-creative
server.creative.shell=mc-console
server.creative.allowed-prefixes=list,say,lp,whitelist字段说明：
container：Docker 容器名。shell：容器内接收 Minecraft 控制台命令的程序。allowed-prefixes：允许执行的命令前缀白名单。
如果需要多个 shell 参数，使用英文逗号分隔：
server.survival.shell=bash,-lc此时 backend 会执行类似：
docker exec minecraft-survival bash -lc "list"AstrBot 侧按 RCON 风格填写 AstrBridge 连接信息：
rcon_host: "Velocity服务器IP"
rcon_port: 25580
rcon_password: "astrbridge.conf 里的 bridge.token"执行 Velocity 代理命令：
/mc-command glist
执行指定 Docker 子服命令：
/mc-command survival list
/mc-command survival say hello
/mc-command creative whitelist list
如果 AstrBot 插件需要直接发送协议内容，使用：
EXEC|survival|300|list
旧格式仍可用于 Velocity 代理命令：
EXEC|300|glist
Velocity 插件启动时会生成：
backend/astrbridge_backend.py
backend/astrbridge_backend.ini
astrbridge_backend.ini 由 astrbridge.conf 自动生成，通常不需要手动编辑。
如果关闭自动启动：
backend.auto-start=false则需要手动运行：
python3 backend/astrbridge_backend.py --config backend/astrbridge_backend.ini原因：没有有效的 server.<name>.container 配置，或自动发现没有匹配到任何 Docker 容器。
处理：
docker ps --format '{{.Names}}'确认容器名后手动配置：
server.survival.container=minecraft-survival
server.survival.shell=mc-console
server.survival.allowed-prefixes=list,say,lp,whitelist或者给容器添加 label：
astrbridge.server=survival
原因：运行 Velocity 的用户无法执行 Docker 命令，或系统没有安装 Docker CLI。
处理：
docker ps如果当前用户执行失败，需要修复 Docker 权限。
原因：AstrBot 请求中的 server 名不存在于生成的 astrbridge_backend.ini。
处理：
- 检查命令里的子服名是否正确。
- 检查
astrbridge.conf是否有对应server.<name>.container。 - 重启 Velocity，让插件重新生成 backend ini。
原因：命令前缀不在 allowed-prefixes 白名单中。
处理：确认确实需要开放该命令后，再加入白名单。
server.survival.allowed-prefixes=list,say,lp,whitelist不要随意开放 op、deop、stop、restart 等高风险命令。
原因：docker exec 执行失败，或容器内的 shell 命令不存在。
处理：
docker exec minecraft-survival mc-console list先在服务器终端确认这条命令可以正常执行。
- 修改所有默认 token。
bridge.host默认保持127.0.0.1；只有 AstrBot 在其他机器时才开放。- 如果开放到局域网或公网，必须配置防火墙和 IP 白名单。
backend.host建议保持127.0.0.1。- 严格维护
allowed-prefixes，只开放确实需要的命令。 - 不要把 AstrBridge 暴露给普通玩家或公开群聊直接调用。
启动失败时按顺序检查：
java -version
python3 --version
docker ps
docker ps --format '{{.Names}}'检查 Velocity 日志：
grep AstrBridge logs/latest.log检查端口监听：
ss -lntp | grep 25580
ss -lntp | grep 25590检查配置文件：
plugins/astrbridge/astrbridge.conf
plugins/astrbridge/backend/astrbridge_backend.ini