1.10. 安装故障排除

1.10.1. 首次安装

如果您的CouchDB在您刚刚安装之后没有启动，请检查以下事项：

  • 在类UNIX系统上，这通常是一个权限问题。确保您已遵循 用户注册和安全 chown/chmod 命令。此问题由关键字的存在表示 eacces 在CouchDB本身的错误输出中的某个地方。
  • 一些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
  • 接下来，确定erlangcouchdb库的安装位置。这通常是您安装的版本的lib/子目录。
  • 使用此命令启动路径中包含CouchDB库的Erlang：
erl -env ERL_LIBS $ERL_LIBS:/path/to/couchdb/lib -couch_ini -s crypto
  • 在那个erlangshell中，让我们检查键库是否正在运行。这个 %% 行是注释，因此可以跳过它们：
%% 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虚拟机。确保您的 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. 升级

你是从couchdb1.x升级的吗？将CouchDB安装到新目录中。CouchDB的目录布局已经改变，可能会被以前版本中的库混淆。

1.10.4. 运行期错误

1.10.4.1. Erlang堆栈跟踪包含 system_limit ， open_port 或 emfile

现代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的安装。当ulimit非常大或无限大时，erlangvm预分配数据结构确实是个问题。详细的讨论可以在erlang问题列表中找到，但是简短的回答是您应该减少 ulimit -n 或者降低 vm.args 参数 +Q 比如1024。

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

如果您在CouchDB错误日志中看到这一点，那么您用于map或reduce函数的JavaScript代码引用的对象成员不是在数据库中至少一个文档中定义的。考虑一下这个文件：

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

这个映射函数：

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

对于上述文档，此操作将失败，因为它不包含 name 或 address 会员。相反，请使用保护来确保该函数只访问文档中存在的成员：

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

虽然上面的保护在大多数情况下都是有效的，但是值得记住JavaScript对“false”值的理解。针对值为0（零）的属性进行测试， '' （空字符串）， false 或 null 将返回false。如果这是不希望的，一个守卫的形式 if (doc.foo !== undefined) 应该会成功的。

如果reduce函数不返回值，也可能导致此错误。例如，此reduce函数将导致错误：

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

函数需要返回一个值：

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

1.10.4.4. erlang堆栈跟踪包含 bad_utf8_character_code

couchdb1.1.1和更高版本包含更严格的UTF8编码处理。如果要从旧版本复制到新版本，则在复制过程中可能会发生此错误。

存在许多变通方法；最简单的方法是对相关CouchDB进行就地升级，然后在复制之前进行压缩。

或者，如果受影响的文档数很少，请使用筛选的复制来仅排除这些文档。

1.10.4.5. FIPS模式

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

下面的消息表示操作系统正在“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 compile flag. Use of the flag results in CouchDB substituting the OpenSSL MD5 function calls with equivalent calls to Erlang's built-in library erlang:md5. 注意：此解决方案可能会导致性能损失。

因为CouchDB不将MD5散列用于加密目的，所以只要系统所有者知道并同意使用“FIPS模式”，此解决方案不会破坏“FIPS模式”的目的。

1.10.4.6. 调试启动

如果您是从头开始编译的，并且在启动CouchDB时遇到问题，那么您可能希望看到更多细节。首先在调试级别启用日志记录：

[log]
level = debug

然后你可以通过 -init_debug +W i +v +V -emu_args 中的旗帜 ERL_FLAGS 环境变量来打开CouchDB开发人员可以用来帮助您的附加调试信息。

然后，使用上提供的链接联系CouchDB开发团队 CouchDB home page 寻求帮助。

1.10.5. macOS已知问题

1.10.5.1. 未定义错误，退出状态134

有时 Verify Installation 失败的原因是 undefined 错误。这可能是由于缺少对Mac的依赖。在日志中，你会发现 couchdb exit_status,134 .

正在安装丢失的 nspr 通过 brew install nspr 解决问题。（参见：https://github.com/apache/couchdb/issues/979)