Overflow Docker 部署指南

这是 Overflow 的 Docker 部署配置，提供了一个开箱即用的 Mirai Console + Overflow 容器化部署方案。

🧪 实验性功能

• ARM64 支持正在开发中！如果您使用 ARM64 设备（如 Apple M1/M2 Mac、树莓派等），可以：
  • 查看 ARM64 支持分支
  • 下载 实验性版本
  • 参与测试和反馈

快速开始

1. 创建项目目录并下载配置文件：

# 创建并进入项目目录
mkdir overflow && cd overflow

# 下载配置文件
curl -O https://raw.githubusercontent.com/sdjnmxd/overflow-docker/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/sdjnmxd/overflow-docker/main/env.example

2. 配置必要的环境变量：

# 复制环境变量示例文件
cp env.example .env

# 编辑 .env 文件，填入你的配置
vim .env  # 或使用其他编辑器

3. 启动服务：

docker compose up -d

服务启动后，你可以：

• 查看日志：docker compose logs -f
• 停止服务：docker compose down
• 重启服务：docker compose restart
• 更新版本：docker compose pull && docker compose up -d

目录说明

服务会自动创建以下目录：

• bots：机器人账号数据（挂载到容器的 /app/overflow/bots）
• config：配置文件（挂载到容器的 /app/overflow/config）
• data：数据文件（挂载到容器的 /app/overflow/data）
• logs：日志文件（挂载到容器的 /app/overflow/logs）

配置说明

必要配置

环境变量	说明	默认值
OVERFLOW_WS_HOST	Onebot 实现的 WebSocket 地址	ws://127.0.0.1:7827
OVERFLOW_TOKEN	Onebot 实现的访问令牌	StarBot

可选配置

系统配置

环境变量	说明	默认值
TZ	时区	Asia/Shanghai
JAVA_OPTS	Java 虚拟机参数	-Xms512M -Xmx1G

注意: 在 Docker 构建的预热阶段会自动添加 -Doverflow.skip-token-security-check=I_KNOW_WHAT_I_AM_DOING 参数以跳过 Overflow 的 token 安全校验，这是为了在容器构建时正常完成依赖预热所必需的。运行时不会添加此参数。

Overflow 配置

环境变量	说明	默认值
OVERFLOW_NO_LOG	关闭日志（开启时不接受漏洞反馈）	false
OVERFLOW_WS_HOST	WebSocket 地址	ws://127.0.0.1:7827
OVERFLOW_REVERSED_WS_PORT	反向 WebSocket 端口	-1
OVERFLOW_TOKEN	访问令牌	StarBot
OVERFLOW_NO_PLATFORM	是否禁用平台信息	false
OVERFLOW_USE_CQ_CODE	是否使用 CQ 码	false
OVERFLOW_RETRY_TIMES	重试次数	5
OVERFLOW_RETRY_WAIT_MILLS	重试等待时间（毫秒）	5000
OVERFLOW_RETRY_REST_MILLS	重试休息时间（毫秒）	60000
OVERFLOW_HEARTBEAT_CHECK_SECONDS	心跳检查间隔（秒）	60
OVERFLOW_USE_GROUP_UPLOAD_EVENT	是否使用群文件上传事件	false
OVERFLOW_RESOURCE_CACHE_ENABLED	是否启用资源缓存	false
OVERFLOW_RESOURCE_CACHE_DURATION	资源缓存保留时间（小时）	168
OVERFLOW_DROP_EVENTS_BEFORE_CONNECTED	是否丢弃连接前的事件	true

mirai-api-http 配置

环境变量	说明	默认值
MIRAI_ENABLE_VERIFY	是否启用验证	true
MIRAI_VERIFY_KEY	验证密钥	StarBot
MIRAI_HTTP_HOST	HTTP 服务监听地址	0.0.0.0
MIRAI_HTTP_PORT	HTTP 服务端口	7827
MIRAI_HTTP_CORS	CORS 配置	*
MIRAI_WS_HOST	WebSocket 服务监听地址	0.0.0.0
MIRAI_WS_PORT	WebSocket 服务端口	7827
MIRAI_HTTP_DEBUG	是否启用调试模式	false
MIRAI_SINGLE_MODE	是否启用单例模式	false
MIRAI_WS_SYNC_ID	WebSocket 同步 ID	-1

本地构建

如果需要本地构建镜像：

# 使用默认版本构建
docker build -t overflow .

# 指定版本构建
docker build -t overflow \
  --build-arg MAVEN_REPO=https://mirrors.huaweicloud.com/repository/maven \
  --build-arg OVERFLOW_VERSION=1.0.5 \
  --build-arg MIRAI_VERSION=2.16.0 \
  --build-arg BOUNCYCASTLE_VERSION=1.64 .

这些参数可以在构建时通过 --build-arg 参数覆盖。

版本管理

镜像版本说明：

• latest: 最新版本，每日自动构建
• x.y.z-mirai.a.b.c: 特定版本号，对应 Overflow 和 Mirai Console 的发布版本

当前集成的组件版本：

• Overflow Core: 1.0.9
• Mirai Console: 2.16.0
• BouncyCastle: 1.64

镜像通过 GitHub Actions 自动构建并推送至 Docker Hub：

• 每日自动检查 Overflow 和 Mirai Console 更新
• 发现新版本时自动构建并推送镜像

支持架构

• linux/amd64
• linux/arm64 (实验性支持，查看 ARM64 分支)

问题反馈

如果您在使用过程中遇到任何问题或有改进建议，欢迎通过以下方式反馈：

1. GitHub Issues：

   • 部署相关问题
   • Docker镜像问题
   • 功能建议
   • 文档改进

2. Overflow 官方仓库：

   • Overflow 本身的功能问题
   • 协议实现问题
   • 其他 Bot 相关问题

提交问题时，请尽可能提供：

• 详细的问题描述
• 相关的错误日志
• 复现步骤
• 运行环境信息

License

本项目采用 MIT License 开源，详细信息请参阅 LICENSE 文件。

Overflow Docker 是一个独立项目，仅提供容器化部署方案。上游项目使用以下许可证：

• Overflow 采用 AGPL-3.0 License，所有权利归原作者所有
• Mirai 采用 AGPL-3.0 License，所有权利归原作者所有