---

【实战记录】Docker 部署 CouchDB 遇坑指南：为何环境变量密码登录失败？

摘要：本文记录了在阿里云 VPS 上使用 Docker Compose 部署 CouchDB 以实现 Obsidian LiveSync 自建同步的过程中，遇到的“密码错误”疑难问题。通过深入分析 Docker 卷挂载机制与 CouchDB 初始化流程，定位了配置目录挂载导致系统数据库初始化失败的根因，并提供了一套完整的重置与最佳实践方案。

关键词：Docker, CouchDB, Obsidian, LiveSync, 卷挂载，故障排查

---

1. 背景与目标

为了实现笔记多端实时同步，我决定自建 Obsidian LiveSync 服务。方案选型为 CouchDB + Caddy，部署环境为阿里云 Ubuntu 服务器。

环境信息：

• 服务器系统：Ubuntu 20.04 LTS
• 部署工具：Docker + Docker Compose
• 目标架构：
  • CouchDB：数据库核心，负责数据同步
  • Caddy：反向代理，自动配置 HTTPS 证书

2. 问题现象

在完成 docker-compose.yml 配置并启动容器后，访问 CouchDB 管理界面（Fauxton）时，使用环境变量中设置的账号密码登录，始终报错

初始配置片段：

services:
  couchdb:
    image: couchdb:latest
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=YourStrongPassword123  # 环境变量设置密码
    volumes:
      - ./data:/opt/couchdb/data
      - ./config:/opt/couchdb/etc/local.d  # 挂载配置目录(✨划重点)

3. 故障排查过程

3.1 初步假设与验证

起初怀疑是密码特殊字符导致解析错误，尝试修改为简单密码 Test1234，问题依旧。随后检查容器日志，发现关键错误信息：

[notice] 2026-03-27T10:42:43.473611Z nonode@nohost <0.328.0> -------- chttpd_auth_cache changes listener died because the _users database does not exist. Create the database to silence this notice.
[error] 2026-03-27T10:42:43.473740Z nonode@nohost emulator -------- Error in process <0.535.0> with exit value:
{database_does_not_exist,[{mem3_shards,load_shards_from_db,"_users",[{file,"src/mem3_shards.erl"},{line,400}]},{mem3_shards,load_shards_from_disk,1,[{file,"src/mem3_shards.erl"},{line,375}]},{mem3_shards,load_shards_from_disk,2,[{file,"src/mem3_shards.erl"},{line,404}]},{mem3_shards,for_docid,3,[{file,"src/mem3_shards.erl"},{line,97}]},{fabric_doc_open,go,3,[{file,"src/fabric_doc_open.erl"},{line,39}]},{chttpd_auth_cache,ensure_auth_ddoc_exists,2,[{file,"src/chttpd_auth_cache.erl"},{line,198}]},{chttpd_auth_cache,listen_for_changes,1,[{file,"src/chttpd_auth_cache.erl"},{line,145}]}]}

划重点

[error] ... chttpd_auth_cache changes listener died because the _users database does not exist.
[warning] ... Authentication failed for user admin from ...

这表明 CouchDB 的 _users 系统数据库未正确创建，导致用户认证系统错误。

3.2 原因分析：卷挂载的“覆盖”效应

通过进入容器内部检查，发现了一个关键现象：

# 进入容器
docker exec -it obsidian-couchdb /bin/bash

# 查看配置目录
ls -la /opt/couchdb/etc/local.d/

发现问题：
当宿主机上的 ./config 目录为空或不存时，Docker 会自动创建一个空目录并将其挂载到容器内的 /opt/couchdb/etc/local.d。这一操作覆盖了容器镜像内默认的配置文件。

简单来说:空白覆盖了Docker中的数据

CouchDB 初始化逻辑：

1. 首次启动时，CouchDB 会读取 /opt/couchdb/etc/local.d/ 下的配置。
2. 若该目录被空挂载覆盖，CouchDB 无法找到必要的初始化配置。
3. 导致 _users 数据库创建失败，环境变量 COUCHDB_USER 设置的-admin 用户无法写入数据库。
4. 即使后续修复了挂载，由于 ./data 卷中已存在损坏的用户数据库文件，环境变量不再生效（数据卷优先级高于环境变量）。

4. 解决方案

4.1 彻底重置数据（推荐首次部署）

由于是首次部署，无重要数据，最干净的方式是清除旧的状态。

# 1. 停止服务
docker compose down

# 2. 备份并清理数据卷与配置卷
mv ./data ./data.backup
mv ./config ./config.backup
mkdir -p ./data ./config

# 3. 修正权限（关键步骤）
# CouchDB 容器内用户 UID 为 5984，需确保目录可写
chmod -R 777 ./data ./config

# 4. 修改 docker-compose.yml
# 临时注释掉 config 挂载，让 CouchDB 使用默认配置初始化
# volumes:
#   - ./data:/opt/couchdb/data
#   # - ./config:/opt/couchdb/etc/local.d  <-- 注释此行

# 5. 重新启动
docker compose up -d

5. 最终配置参考

以下是经过验证的稳定 docker-compose.yml 配置：

version: '3.8'

services:
  couchdb:
    image: couchdb:latest
    container_name: obsidian-couchdb
    restart: unless-stopped
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=[你的强密码]  # 建议包含大小写字母、数字、特殊符号
    volumes:
      - ./data:/opt/couchdb/data
      # 首次启动建议注释，稳定后可开启
      # - ./config:/opt/couchdb/etc/local.d
    networks:
      - obsidian-net
  
  caddy:
    image: caddy:latest
    container_name: obsidian-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - couchdb
    networks:
      - obsidian-net

networks:
  obsidian-net:
    driver: bridge

volumes:
  caddy_data:
  caddy_config:

6. 结语

希望本文能帮助遇到类似问题的开发者少走弯路