EPrints 3.4.7 Ubuntu 22.04 安装部署指南

目标：在 Ubuntu 22.04.5 LTS 上以官方源码 tarball（v3.4.7）完成 EPrints 机构知识库的裸机部署——从 apt 依赖安装、源码落位 /opt/eprints3、eprints 系统用户创建，到 epadmin create 建库向导逐问逐答、Apache mod_perl 集成、epindexer 索引服务启动，直至 BibTeX 导入一条记录走完 buffer→archive 发布链路并通过检索、OAI-PMH 与后台登录三重验证。全程命令与回显均为实测，7 则排障实录逐条入册。产品定位与选型论证见 《EPrints 介绍与选型指南》，配置体系详解见本专栏配置篇《EPrints 配置参数详解（cfg.d 分层体系与关键项）》，命令行管理见本专栏 CLI 篇《EPrints 常用 CLI 命令详解》。

一、部署架构与目标环境

EPrints 3.4 是典型的"单体 mod_perl 应用"：全部业务逻辑为 Perl 模块，常驻 Apache 工作进程；元数据入 MySQL/MariaDB，全文索引由进程内 Xapian 库承担（无独立检索服务），上传文件与静态页落在文件系统 archives/<id>/ 下。一套 /opt/eprints3 安装可承载多个相互独立的 archive（本实测环境先后建立 demo、demo2 两个库，互不干扰），这是它区别于 DSpace/InvenioRDM 的招牌形态。

实测环境版本（均为命令实测回显）：

部署形态说明：官方 Debian 包（eprints 包，Maintainer: EPrints Software software@eprints.org）与源码 tarball 两条路径的运行时内容一致；3.4.7 的 GitHub 源码 tarball 解包后无需 configure/make 编译，bin/epadmin 可直接运行——lib/cfg.d、flavours/pub_lib 即默认配置源。本篇按源码路径实测。

二、安装系统依赖

依赖清单以官方 Debian 包 control 文件的 Depends 为准（查询日期 2026-11-01），核心项如下：

apt-get install -y perl apache2 libapache2-mod-perl2 \
  libdbd-mysql-perl libxml-libxml-perl libxml-parser-perl libxml-twig-perl \
  libxml2-dev libunicode-string-perl libterm-readkey-perl \
  libmime-lite-perl libmime-types-perl libdigest-sha-perl \
  libarchive-any-perl libjson-perl libconfig-general-perl \
  liblwp-protocol-https-perl libtext-unidecode-perl libio-string-perl \
  libtex-encode-perl libsearch-xapian-perl \
  mariadb-server mariadb-client lynx wget unzip tar gzip \
  poppler-utils imagemagick ghostscript

装完后系统内 lib*-perl 包共 78 个（dpkg -l 'lib*-perl' | grep -c '^ii' 实测计数）。关键 Perl 包实测在册：libapache2-mod-perl2 libarchive-any-perl libconfig-general-perl libconfig-inifiles-perl libdbd-mysql-perl libdigest-sha-perl libhtml-template-perl libio-string-perl libjson-perl liblwp-protocol-https-perl libmime-lite-perl libmime-types-perl libsearch-xapian-perl libterm-readkey-perl libtex-encode-perl libtext-unidecode-perl libunicode-string-perl libxml-libxml-perl libxml-parser-perl libxml-twig-perl。

外部工具链（全文抽取与文档处理）实测在册：poppler-utils（pdftotext）、imagemagick（convert，缩略图）、ghostscript、lynx、wget、unzip。缺 antiword/unoconv/ffmpeg 只影响旧版 Word/办公文档/视频的全文抽取与转码，不阻塞部署。

💡 技术拓展：libterm-readkey-perl 是 epadmin 交互向导的硬依赖（终端逐问逐答读取），libsearch-xapian-perl 是检索的硬依赖——这两项漏装分别表现为建库向导无法问答、检索页 500，是 apt 路径最常踩的两个坑。

三、获取源码并落位 /opt/eprints3

wget https://github.com/eprints/eprints/archive/refs/tags/3.4.7.tar.gz -O eprints-3.4.7.tar.gz
tar xzf eprints-3.4.7.tar.gz
mv eprints-3.4.7 /opt/eprints3

实测包体 14M（GitHub codeload tar，含 configure.ac 但无需执行 autotools 流程）。落位后的关键目录：

站点级系统配置 perl_lib/EPrints/SystemSettings.pm 实测在册（节选）：

$EPrints::SystemSettings::conf = {
	'version' => 'EPrints 3.4.7',
	'base_path' => '/opt/eprints3',
	'group' => 'eprints',
	'user' => 'eprints',
	'file_perms' => '0664',
	'smtp_server' => '127.0.0.1',
	...

其中 user/group 指向 eprints——下一节必须先建该用户，否则任何 bin/ 工具直接报错（见第十一节排障 1）。

四、创建 eprints 系统用户

按 SystemSettings 声明创建同名用户与组，家目录指向安装路径、登录 shell 设为 nologin。实测创建结果（getent 回显）：

# getent passwd eprints
eprints:x:106:108:EPrints,,,:/opt/eprints3:/usr/sbin/nologin
# getent group eprints
eprints:x:108:www-data

即 eprints 用户 uid=106、组 gid=108，且 www-data 已加入 eprints 组（Apache 工作进程以 www-data 身份运行，需要写 archive 的 html/var/documents 目录，见第八节）。EPrints 对运行身份有强校验：bin/epadmin 系列命令必须以 eprints 用户执行，标准姿势是：

su eprints -s /bin/bash -c 'cd /opt/eprints3 && ./bin/epadmin <command> ...'

五、数据库准备（MariaDB）

建库向导会代建 archive 数据库与库用户，但需要以数据库超级用户（root）身份连接。Ubuntu 22.04 的 MariaDB root 默认走 unix_socket 认证，epadmin 以 eprints 身份经 socket 连接会直接报 1698（见第十一节排障 3）。先给 root 设置密码认证：

ALTER USER 'root'@'localhost' IDENTIFIED BY 'q1w2e3r4';

⚠️ 本篇示例账号密码统一为 q1w2e3r4（root/admin 等），生产环境务必更换。

六、epadmin create 建库向导全流程实录

以 pub 口味创建第一个 archive demo（./bin/epadmin create pub）。向导逐问逐答，下表为实测提示原文与输入值（提示文本摘自建库日志逐行回显；第二个库 demo2 的完整建库日志同样为实测，交互顺序一致）：

向导收尾回显（实测原文节选）：

--------------------------------------------------------------------------
That seemed to more or less work ...
--------------------------------------------------------------------------
Make sure that your main apache config file contains the line:

 Include /opt/eprints3/cfg/apache.conf

Then stop and start your webserver:
...
Don't forget to register your repository at http://roar.eprints.org/

usertype 的合法取值定义在 lib/namedsets/user：user/editor/admin 三档。建库完成后 archives/demo/cfg/cfg.d/ 实测共 6 个文件：00_flavour.pl（$c->{flavour} = 'pub';）、10_core.pl、adminemail.pl、citationcaches.pl、csrf_protection.pl、database.pl，逐项详解见本专栏配置篇《EPrints 配置参数详解（cfg.d 分层体系与关键项）》。

七、Apache 集成

Ubuntu 的 Apache 集成四步（实测）：

# 1. 启用 mod_perl 与必需模块（deflate/filter/perl 为 mod_perl 依赖默认已开）
a2enmod rewrite headers
# 2. 让 Apache 监听 8141：/etc/apache2/ports.conf 追加
echo "Listen 8141" >> /etc/apache2/ports.conf
# 3. 挂载 EPrints 主配置：/etc/apache2/conf-available/eprints.conf 内容一行
#    Include /opt/eprints3/cfg/apache.conf
a2enconf eprints
# 4. 生成各 archive 的虚拟主机配置（建库向导已代做，可重跑）
su eprints -s /bin/bash -c 'cd /opt/eprints3 && ./bin/generate_apacheconf --replace'
apache2ctl restart

generate_apacheconf 无参重跑的实测回显：

Wrote /opt/eprints3/cfg/perl_module_isolation.conf
Wrote /opt/eprints3/cfg/perl_module_isolation_vhost.conf

No files were changed. For more information do ./generate_apacheconf --man

生成的 cfg/apache/demo.conf 核心（实测文件内容）：

<VirtualHost *:8141>
  ServerName 127.0.0.1
  ServerAdmin admin@eprints.qzuo.local
    Include /opt/eprints3/cfg/perl_module_isolation_vhost.conf
  <Location "">
    PerlSetVar EPrints_ArchiveID demo
    Options +ExecCGI
    <IfModule mod_authz_core.c>
       Require all granted
    </IfModule>
  </Location>
  # Set by $c->{max_upload_filesize}
  LimitRequestBody 1073741824
  # Note that PerlTransHandler can't go inside
  # a "Location" block as it occurs before the
  # Location is known.
  PerlTransHandler +EPrints::Apache::Rewrite
</VirtualHost>

路由机制：PerlTransHandler +EPrints::Apache::Rewrite 把 /id/eprint/1/、/cgi/users/home 这类"美化 URL"翻译成 CGI 调用，PerlSetVar EPrints_ArchiveID demo 声明该虚拟主机归属哪个 archive——多 archive 就是多个 VirtualHost 各挂一个 ArchiveID。rewrite/headers 模块缺失时表现为 URL 重写失效与缓存头报错（实测 apache2ctl -M 在册：deflate/headers/perl/rewrite 四项 shared）。

八、权限修复（静态资源写入）

Apache 工作进程（www-data）需要写 archive 的静态页、日志与上传目录，否则首页加载时 auto.js 等动态生成文件写入失败、页面 500。实测修复：

usermod -aG eprints www-data
chgrp -R eprints archives/demo/html archives/demo/var archives/demo/documents
chmod -R g+w archives/demo/html archives/demo/var archives/demo/documents
chgrp -R eprints /opt/eprints3/var && chmod -R g+w /opt/eprints3/var

九、启动索引服务 epindexer

EPrints 的 Xapian 索引由常驻工具 bin/epindexer 增量构建（新记录/改记录后 30 秒级入库）。源码 tarball 的 bin/epindexer 是未替换占位符的模板（bin/epindexer.in 同名并存），直接运行报路径错误，实测修复：

sed -i "s|EPRINTS_PATH|/opt/eprints3|g" bin/epindexer
./bin/epindexer start    # 以 root 运行（实测本环境形态）
./bin/epindexer status

status 实测回显：

Indexer is running with PID 547. Next index in 30 seconds.

索引日志 var/indexer.log 实测尾部：

[Sun Nov  1 12:57:55 2026] 547 ** Indexer process started
[Sun Nov  1 12:57:55 2026] 547 *** Starting indexer sub-process
/opt/eprints3/archives/demo/var/last_changed.timestamp has been modified since the repository config was loaded: reloading!

十、端到端验证：导入→发布→检索→OAI

准备一条 BibTeX 记录（sample.bib，作者 Zhang, San 与 Li, Si 的机构库实践评估论文），走完整链路。

1. 导入（进 buffer）——实测命令与回显：

# su eprints -s /bin/bash -c 'cd /opt/eprints3 && ./bin/import demo --force --verbose --user 1 eprint BibTeX /work/sample.bib'
Starting EPrints Repository.
Connecting to DB ... done.
Warning! Importing an EPrint record into 'eprint' dataset without eprint_status being set. Using 'buffer' as default.
Number of records imported: 1
1
Ending EPrints Repository.

2. 发布（buffer→archive）——EPrints API 没有 set_status/reindex 方法，用 move_to_archive（实测脚本）：

#!/usr/bin/perl -w
use strict;
use lib "/opt/eprints3/perl_lib";
use EPrints;

my $repository = EPrints->new->repository("demo");
my $dataobj = EPrints::DataObj::EPrint->new($repository, 1);
$dataobj->move_to_archive;
$repository->logout_current_user;
exit;

发布后状态实测：eprint 1 eprint_status = archive。

3. 摘要页：curl -s http://127.0.0.1:8141/id/eprint/1/ 取 <title> 实测回显：

<title> Building Institutional Repositories with EPrints: A Practical Evaluation  - Qzuo Demo Repository</title>

4. 全文检索：/cgi/search?q=EPrints 实测结果页关键片段：

<title>Search results for EPrints - Qzuo Demo Repository</title>
Search results for <span class="search_desc">EPrints</span>
Displaying results 1 to 1 of 1.

5. OAI-PMH：curl "http://127.0.0.1:8141/cgi/oai2?verb=Identify" 实测回显节选：

<Identify>
  <repositoryName>Qzuo Demo Repository</repositoryName>
  <baseURL>http://127.0.0.1:8141/cgi/oai2</baseURL>
  <protocolVersion>2.0</protocolVersion>
  <adminEmail>admin@eprints.qzuo.local</adminEmail>
  <earliestDatestamp>2026-11-01T12:56:19Z</earliestDatestamp>
  <deletedRecord>persistent</deletedRecord>
</Identify>

ListRecords&metadataPrefix=oai_dc 实测返回该记录：<identifier>oai:127.0.0.1:1</identifier>、<dc:title>Building Institutional Repositories with EPrints: A Practical Evaluation</dc:title>、<dc:creator>Zhang, San</dc:creator> 等。

6. 导出回环：./bin/export demo --verbose eprint BibTeX 1 实测回显节选：

            year = {2026},
           pages = {45--67},
          volume = {12},
          number = {3},
           title = {Building Institutional Repositories with EPrints: A Practical Evaluation},
          author = {Zhang, San and Li, Si},
        keywords = {institutional repository, metadata, open access},
             url = {http://127.0.0.1:8141/id/eprint/1/}
}
Ending EPrints Repository.

7. 管理后台：/cgi/users/home 未登录实测返回 401，以 admin/q1w2e3r4 通过 HTTP Basic 认证（realm=Qzuo Demo Repository）后实测返回 200。

8. 首页：curl -I http://127.0.0.1:8141/ 实测回显：

HTTP/1.1 200 OK
Date: Sun, 01 Nov 2026 13:14:28 GMT
Server: Apache/2.4.52 (Ubuntu)
Cache-Control: no-store, no-cache, must-revalidate
Content-Type: text/html; charset=utf-8

十一、排障实录（7 则）

1. epadmin 报用户不存在：装完源码立刻跑 bin/epadmin 实测报错：

   'eprints' is not a valid user on this system - check your SystemSettings
   

   原因：SystemSettings.pm 声明的 eprints 系统用户尚未创建。解法：第四节建用户后消除。
2. epadmin 以 root 运行被拒：实测报错：

   We appear to be running as user: root (0)
   We expect to be running as user: eprints (106)
   

   EPrints 强校验运行身份。解法：统一 su eprints -s /bin/bash -c 'cd /opt/eprints3 && ./bin/epadmin ...'。
3. 建库向导连不上数据库（错误 1698）：向导以 root 建库时报 Access denied for user 'root'@'localhost' (using password: NO) 类 1698。根因：MariaDB 10.6 的 root 默认 unix_socket 认证（auth_string=invalid），epadmin 以 eprints 身份走 socket 认证失败。解法：第五节 ALTER USER 'root'@'localhost' IDENTIFIED BY 'q1w2e3r4' 改密码认证。
4. import 插件名大小写敏感：./bin/import demo ... eprint bibtex file.bib（小写）实测报 Plugin not found；插件名须首字母大写：BibTeX。且参数顺序为 dataset 在前、plugin 在后：import <repo> [options] <dataset> <plugin> <filename>。
5. import 无 --force 挂起：不加 --force 时向导逐条等待确认，管道场景直接挂起。解法：--force 跳过交互。
6. 首页 500 / auto.js 写入失败：Apache 以 www-data 运行但 archive 的 html/var/documents 属组不可写。解法：第八节 usermod -aG eprints www-data + chgrp -R eprints + chmod -R g+w。
7. 检索页 500：/cgi/search?q=X 先 302 到 /cgi/search/simple，实测 500。根因：archives/demo/var/xapian 索引目录不存在（epindexer 从未成功跑过）。解法：mkdir 该目录并 chgrp/g+w，启动 epindexer 建索引后检索恢复（第十节 4 实测 1 result）。

另有一则无害噪音：管道喂 epadmin 交互时 Term::ReadKey 报 Unable to get Terminal Size. The TIOCGWINSZ ioctl didn't work...，不影响执行，可 grep -v "Terminal Size" 过滤。

十二、部署检查清单

十三、参考链接

1. EPrints GitHub 仓库（v3.4.7 tarball）：https://github.com/eprints/eprints （查询日期 2026-11-01）
2. EPrints 官方 wiki 安装指南：https://wiki.eprints.org/w/Installation （查询日期 2026-11-01）
3. 官方 Debian 包 control 文件（依赖清单口径）：https://github.com/eprints/eprints 仓库打包元数据 （查询日期 2026-11-01）
4. Apache mod_perl 文档：https://perl.apache.org/docs/ （查询日期 2026-11-01）
5. MariaDB 认证插件（unix_socket）说明：https://mariadb.com/kb/en/authentication-unix_socket/ （查询日期 2026-11-01）
6. Xapian Perl API：https://xapian.org/docs/ （查询日期 2026-11-01）
7. 站内同家族选型篇：《EPrints 介绍与选型指南》；竞品视角参见 《DSpace 介绍与选型指南》