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 或邮件列表中。
记下您的操作系统的名称和版本以及您的处理器架构。
记下 CouchDB 依赖项的已安装版本。
按照签出说明获取 CouchDB 主干的新副本。
从 couchdb 目录配置
./configure
构建版本
make release
运行 couchdb 命令并记录输出
cd rel/couchdb
bin/couchdb
使用您系统的内核跟踪工具并记录上述命令的输出。
例如,linux 系统应使用
strace
strace bin/couchdb 2> strace.out
将每个步骤的输出报告给邮件列表(或 IRC)。
1.10.3. 升级¶
您是否从 CouchDB 1.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 安装。这实际上是 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);
}
这将在上述文档上失败,因为它不包含 name
或 address
成员。相反,请使用保护以确保函数仅在成员存在于文档中时才访问它们
function(doc) {
if(doc.name && doc.address) {
emit(doc.name, doc.address);
}
}
虽然上述保护在大多数情况下都有效,但值得注意的是 JavaScript 对“false”值的理解。针对具有 0(零)、''
(空字符串)、false
或 null
值的属性进行测试将返回 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)