1.10. 安装故障排除

1.10.1. 首次安装

如果您的 CouchDB 在您刚安装后无法启动,请检查以下事项

  • 在类 Unix 系统上,这通常是权限问题。确保您已按照 用户注册和安全 chown/chmod 命令操作。此问题由 CouchDB 本身错误输出中出现关键字 eacces 所指示。

  • 一些 Linux 发行版将 Erlang 分成多个软件包。对于您的发行版,请检查您是否确实安装了所有必需的 Erlang 模块。这因平台而异,因此您只需自行解决。例如,在最近版本的 Ubuntu/Debian 上,erlang 软件包包含所有 Erlang 模块。

  • 确认 Erlang 本身在启动时支持加密 (SSL)

## what version of erlang are you running? Ensure it is supported
erl -noshell -eval 'io:put_chars(erlang:system_info(otp_release)).' -s erlang halt
## are the erlang crypto (SSL) libraries working?
erl -noshell -eval 'case application:load(crypto) of ok -> io:put_chars("yay_crypto\n") ; _ -> exit(no_crypto) end.' -s init stop
  • 接下来,确定您的 Erlang CouchDB 库安装的位置。这通常是您安装的版本的 lib/ 子目录。

  • 使用此命令在 Erlang 的路径中启动 Erlang,其中包含 CouchDB 库

erl -env ERL_LIBS $ERL_LIBS:/path/to/couchdb/lib -couch_ini -s crypto
  • 在该 Erlang shell 中,让我们检查关键库是否正在运行。%% 行是注释,因此您可以跳过它们

%% test SSL support. If this fails, ensure you have the OTP erlang-crypto library installed
crypto:md5_init().

%% test Snappy compression. If this fails, check your CouchDB configure script output or alternatively
%% if your distro comes with erlang-snappy make sure you're using only the CouchDB supplied version
snappy:compress("gogogogogogogogogogogogogogo").

%% test the CouchDB JSON encoder. CouchDB uses different encoders in each release, this one matches
%% what is used in 2.0.x.
jiffy:decode(jiffy:encode(<<"[1,2,3,4,5]">>)).

%% this is how you quit the erlang shell.
q().
  • 输出应类似于此,否则将抛出错误

Erlang/OTP 17 [erts-6.2] [source] [64-bit] [smp:2:2] [async-threads:10] [kernel-poll:false]

Eshell V6.2  (abort with ^G)
1> crypto:md5_init().
<<1,35,69,103,137,171,205,239,254,220,186,152,118,84,50,
  16,0,0,0,0,0,0,0,0,0,0,0,0,0,...>>
2> snappy:compress("gogogogogogogogogogogogogogo").
{ok,<<28,4,103,111,102,2,0>>}
3> jiffy:decode(jiffy:encode(<<"[1,2,3,4,5]">>)).
<<"[1,2,3,4,5]">>
4> q().
  • 此时,唯一剩下的依赖项是您系统的 Unicode 支持库 ICU 和来自 Mozilla 的 Spidermonkey Javascript VM。确保您的 LD_LIBRARY_PATH 或非 Linux 系统的等效项 (DYLD_LIBRARY_PATH 在 macOS 上) 使这些库可供 CouchDB 使用。Linux 示例以普通用户身份运行

  LD_LIBRARY_PATH=/usr/local/lib:/usr/local/spidermonkey/lib couchdb

Linux example running as couchdb user:
echo LD_LIBRARY_PATH=/usr/local/lib:/usr/local/spidermonkey/lib couchdb | sudo -u couchdb sh
  • 如果您收到包含关键字 eaddrinuse 的错误消息,例如

  Failure to start Mochiweb: eaddrinuse

edit your ``etc/default.ini`` or ``etc/local.ini`` file and change the
``[chttpd] port = 5984`` line to an available port.
  • 如果您收到包含字符串的错误

… OS Process Error … {os_process_error,{exit_status,127}}

那么可能是您的 SpiderMonkey JavaScript VM 安装不正确。请重新检查您的构建依赖项并重试。

  • 如果您收到包含字符串的错误

… OS Process Error … {os_process_error,{exit_status,139}}

这是因为 SELinux 阻止访问文件系统的某些区域。您必须重新配置 SELinux,或者可以使用以下命令完全禁用 SELinux

setenforce 0
  • 如果您仍然无法启动 CouchDB,请继续阅读。

1.10.2. 快速构建

在首次运行 CouchDB 时遇到问题?按照以下简单步骤操作,并将每个步骤的输出报告给用户邮件列表或 IRC。请将这些步骤的输出放入粘贴服务(例如 https://paste.ee/)中,而不是直接将整个运行输出包含在 IRC 或邮件列表中。

  1. 记下您的操作系统的名称和版本以及您的处理器架构。

  2. 记下 CouchDB 依赖项的已安装版本。

  3. 按照签出说明获取 CouchDB 主干的新副本。

  4. 从 couchdb 目录配置

./configure
  1. 构建版本

make release
  1. 运行 couchdb 命令并记录输出

cd rel/couchdb
bin/couchdb
  1. 使用您系统的内核跟踪工具并记录上述命令的输出。

    1. 例如,linux 系统应使用 strace

strace bin/couchdb 2> strace.out
  1. 将每个步骤的输出报告给邮件列表(或 IRC)。

1.10.3. 升级

您是否从 CouchDB 1.x 升级?将 CouchDB 安装到一个新的目录中。CouchDB 的目录布局已更改,可能会与先前版本中存在的库混淆。

1.10.4. 运行时错误

1.10.4.1. Erlang 堆栈跟踪包含 system_limitopen_portemfile

现代 Erlang 的默认端口限制为 65536 个端口(Windows 上为 8196 个),其中每个打开的文件句柄、tcp 连接和链接的驱动程序使用一个端口。操作系统对每个进程的打开句柄数量有不同的软限制和硬限制,通常低至 1024 或 4096 个文件。您可能已经超过了这个限制。

需要更改两个设置才能增加此值。请参阅您的操作系统文档,了解如何为您的进程增加限制。在 Linux 和 systemd 下,可以通过 systemctl edit couchdb 并添加以下行来调整此设置

[Service]
LimitNOFILE=65536

到编辑器中的文件。

要将此值增加到超过 65536,您还必须将 Erlang +Q 参数添加到您的 etc/vm.args 文件中,方法是添加以下行

+Q 102400

旧的 ERL_MAX_PORTS 环境变量被 CouchDB 附带的 Erlang 版本忽略。

1.10.4.2. 启动时使用大量内存

您的 CouchDB 在启动时是否使用了大量内存(数百 MB)?这个问题似乎特别影响 Dreamhost 安装。这实际上是 Erlang VM 在 ulimit 非常大或无限制时预先分配数据结构的问题。您可以在 erlang-questions 列表中找到详细的讨论,但简而言之,您应该将 ulimit -n 降低或将 vm.args 参数 +Q 降低到合理的值,例如 1024。

1.10.4.3. 函数引发异常 (无法将“undefined”值编码为 JSON)

如果您在 CouchDB 错误日志中看到此错误,则您用于映射或归约函数的 JavaScript 代码正在引用在数据库中至少一个文档中未定义的对象成员。请考虑以下文档

{
  "_id":"XYZ123",
  "_rev":"1BB2BB",
  "field":"value"
}

以及此映射函数

function(doc) {
  emit(doc.name, doc.address);
}

这将在上述文档上失败,因为它不包含 nameaddress 成员。相反,请使用保护以确保函数仅在成员存在于文档中时才访问它们

function(doc) {
  if(doc.name && doc.address) {
    emit(doc.name, doc.address);
  }
}

虽然上述保护在大多数情况下都有效,但值得注意的是 JavaScript 对“false”值的理解。针对具有 0(零)、''(空字符串)、falsenull 值的属性进行测试将返回 false。如果这是不希望的,则形式为 if (doc.foo !== undefined) 的保护应该可以解决问题。

如果归约函数没有返回值,也会导致此错误。例如,此归约函数将导致错误

function(key, values) {
  sum(values);
}

该函数需要返回值

function(key, values) {
  return sum(values);
}

1.10.4.4. Erlang 堆栈跟踪包含 bad_utf8_character_code

CouchDB 1.1.1 及更高版本包含更严格的 UTF8 编码处理。如果您从旧版本复制到新版本,则在复制过程中可能会出现此错误。

存在许多解决方法;最简单的方法是对相关的 CouchDB 进行就地升级,然后在复制之前进行压缩。

或者,如果受影响的文档数量很少,请使用过滤复制来排除这些文档。

1.10.4.5. FIPS 模式

操作系统可以配置为禁止使用 OpenSSL MD5 哈希函数,以防止将 MD5 用于加密目的。CouchDB 使用 MD5 哈希来验证数据的完整性(而不是用于加密),如果没有使用 MD5 哈希的能力,CouchDB 将无法运行。

下面的消息表明操作系统正在“FIPS 模式”下运行,该模式除了其他限制外,还禁止使用 OpenSSL 的 MD5 函数。

md5_dgst.c(82): OpenSSL internal error, assertion failed: Digest MD5 forbidden in FIPS mode!
[os_mon] memory supervisor port (memsup): Erlang has closed
[os_mon] cpu supervisor port (cpu_sup): Erlang has closed
Aborted

可以使用 --erlang-md5 编译标志来解决此问题。使用此标志会导致 CouchDB 将 OpenSSL MD5 函数调用替换为对 Erlang 内置库 erlang:md5 的等效调用。注意:此解决方法可能会导致性能下降。

由于 CouchDB 不将 MD5 哈希用于加密目的,因此只要系统所有者了解并同意使用此解决方法,它就不会破坏“FIPS 模式”的目的。

1.10.4.6. 调试启动

如果您是从头开始编译的,并且在启动 CouchDB 时遇到问题,您可能需要查看更多详细信息。首先,在调试级别启用日志记录。

[log]
level = debug

然后,在 ERL_FLAGS 环境变量中传递 -init_debug +W i +v +V -emu_args 标志,以打开 CouchDB 开发人员可以使用来帮助您的其他调试信息。

然后,使用 CouchDB 主页 上提供的链接联系 CouchDB 开发团队以寻求帮助。

1.10.5. macOS 已知问题

1.10.5.1. undefined 错误,exit_status 134

有时 Verify Installation 会出现 undefined 错误。这可能是由于 Mac 上缺少依赖项。在日志中,您将找到 couchdb exit_status,134

通过 brew install nspr 安装缺少的 nspr 可以解决此问题。(参见:https://github.com/apache/couchdb/issues/979