运行单实例ArangoDB的Docker容器环境配置及优化方法

一、单机版官方镜像支持的核心环境变量 #

ArangoDB单机镜像（镜像tag不带cluster后缀的标准官方版本）不识别集群专属配置，所有可用环境变量分三类：

基础连接类（启动必配，避免连不上） #

• ARANGO_ROOT_PASSWORD：root账号初始密码，非localhost访问时必填，testcontainers场景必须显式设置，否则容器默认会拒绝来自容器外的连接请求。
• ARANGO_NO_AUTH：值设为1时关闭全量身份认证，仅本地临时测试可用，禁止在任何对外暴露的场景配置。
• ARANGO_DATABASE：容器首次启动时自动创建的自定义业务库，省掉启动后手动建库的步骤，适合测试场景预置环境。
• ARANGO_USER/ARANGO_PASSWORD：首次启动时自动创建的普通业务账号，会自动授予前面自定义库的读写权限，测试场景可以直接用这个账号连接，避免用高权限root账号跑用例。

资源优化类（对应ES_JAVA_OPTS类调优参数） #

注意：ArangoDB核心为C++实现，无JVM运行时，不存在类似ES的JVM参数配置项，所有资源适配直接用官方提供的以下参数即可：

• ARANGODB_OVERRIDE_DETECTED_MEMORY：最核心的内存配置项，单位为字节，用于手动告知ArangoDB进程当前可用的总内存。容器场景下因为cgroup版本兼容问题，经常出现进程自动读取内存限制不准的问题，手动传这个值可以避免内存分配过大触发OOM，比如给容器分配2G内存就设为2147483648。
• ARANGODB_OVERRIDE_DETECTED_NUMBER_OF_CORES：手动告知进程可用CPU核心数，避免自动识别不准导致线程池开得过多触发上下文切换开销，或者开得过少性能不足，比如给容器分配2核就设为2。
• ARANGO_STORAGE_ENGINE：指定存储引擎，单机版默认就是rocksdb，支持事务、性能稳定，不用修改。
• ROCKSDB_MAX_WRITE_BUFFER_NUMBER/ROCKSDB_WRITE_BUFFER_SIZE：RocksDB存储引擎的细粒度内存参数，如果容器分配内存小于1G，可以把前者设为2、后者设为268435456（256MB），限制RocksDB写缓存占用，避免挤掉进程其他部分的内存配额。

启动行为类（减少不必要的启动开销） #

• ARANGO_NO_JWTSECRET_GENERATION：值设为1时，容器不会每次启动随机生成JWT认证密钥，测试场景下配置可以避免容器重启后旧的认证令牌失效。
• ARANGODB_ARGS：直接追加arangod进程的启动参数，比如要开启慢查询日志就传--query.slow-threshold 1000000（单位为微秒，这里阈值是1秒），不需要修改容器启动入口。

二、testcontainers运行时启动最优配置方法 #

1. 资源配额和配置要对齐 #

给容器设置明确的内存、CPU硬限制，测试场景下单节点ArangoDB分配1C2G或者2C1G足够覆盖大部分单测、集成测场景，前面提到的两个OVERRIDE开头的资源参数值，必须和你给容器设置的硬配额完全一致，否则ArangoDB会按宿主机全量资源算内存配额，大概率启动就因为OOM被kill。

2. 裁剪不必要的启动步骤提速 #

• 测试场景不需要持久化数据时，直接用容器内部临时存储，不要挂载宿主机目录，避免额外IO开销拖慢启动速度。
• 通过ARANGODB_ARGS追加--log.level warning参数，减少info级别的日志输出，降低IO压力。
• 不需要Foxx接口服务、不需要自动升级数据格式时，追加--foxx.api false --database.auto-upgrade false参数，能省掉30%左右的启动耗时。

3. 健康检查不要用固定等待时长 #

不要用固定sleep等服务启动，直接用ArangoDB自带的/_api/version接口做HTTP健康检查，接口返回200状态码就说明服务完全就绪，比固定等待靠谱，也不会出现代码提前连库报错的问题。

Go testcontainers配置示例 #

req := testcontainers.ContainerRequest{
    Image:        "arangodb:3.12", // 选明确版本号的稳定单机镜像，不要用latest
    ExposedPorts: []string{"8529/tcp"},
    Env: map[string]string{
        "ARANGO_ROOT_PASSWORD":                      "test_pass_123",
        "ARANGO_DATABASE":                           "test_db",
        "ARANGODB_OVERRIDE_DETECTED_MEMORY":         "2147483648", // 和下面内存配额一致：2G
        "ARANGODB_OVERRIDE_DETECTED_NUMBER_OF_CORES": "2", // 和下面CPU配额一致：2核
        "ARANGO_NO_JWTSECRET_GENERATION":            "1",
        "ARANGODB_ARGS":                             "--log.level warning --foxx.api false --database.auto-upgrade false",
    },
    HostConfigModifier: func(hc *container.HostConfig) {
        hc.Memory = 2147483648 // 给容器设2G硬内存限制
        hc.CPUShares = 2048    // 对应2核的CPU权重
    },
    // 带认证的HTTP健康检查
    WaitingFor: wait.ForHTTP("/_api/version").WithPort("8529/tcp").WithBasicAuth("root", "test_pass_123"),
}

注意：不要给单机镜像传任何集群相关的环境变量，比如ARANGO_CLUSTER_AGENCY_ENDPOINTS这类参数单机镜像不识别，传了会直接导致容器启动失败。

内容的提问来源于stack exchange，提问作者Aditya Vashist