EPrints 常用 CLI 命令详解

目标：以实测环境（Ubuntu 22.04.5 + EPrints 3.4.7，archive demo/demo2）为样本，系统讲解 EPrints 命令行管理套件——bin/epadmin 全部 33 个子命令（--help 原文逐条）、bin/import/bin/export 导入导出、bin/epindexer 索引守护、generate_static/generate_apacheconf/import_subjects 生成类工具，以及绕过 CLI 直接用 EPrints API 脚本操作记录的姿势。全部回显实测照抄，含两处真实失败实录。部署背景见 《EPrints 3.4.7 Ubuntu 22.04 安装部署指南》，配置体系见 《EPrints 配置参数详解（cfg.d 分层体系与关键项）》。

一、环境信息与工具清单

EPrints 的全部管理入口在 /opt/eprints3/bin/，实测目录清单（22 项）：

check_xapian  epadmin  epindexer  epindexer.in  export  generate_abstracts
generate_apacheconf  generate_sitemap  generate_static  generate_views  import
import_subjects  indexer  issues_audit  junit_tests  lift_embargos
remove_citation_caches  run_staged_tasks  send_alerts  startup.pl  toolbox  unit_tests

运行身份铁律：所有命令必须以 eprints 用户执行，root 直跑实测报错（实录见安装篇排障 2）：

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

标准姿势：

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

版本自证（实测）：

# ./bin/epadmin --version
epadmin 3.4.7 [Schema 3.3.4]

Copyright 2024 University of Southampton.
EPrints 3.4 is supplied by EPrints Services.

💡 技术拓展：epadmin 3.4.7 [Schema 3.3.4] 中括号里的 Schema 号是数据库结构版本——升级程序与表结构解耦，epadmin upgrade 就是按 Schema 差量补表的动作（见第七节）。

二、epadmin 全景：33 个子命令

./bin/epadmin --help 实测输出的命令全集（33 个，按用途分组）：

通用选项（--help 实测原文）：--help 简帮助、--man 完整手册、--verbose 详细执行（可叠加）、--force 免确认、--version 版本、--quiet（原文注明 "This option does not do anything"，占位）。

三、建库与对象管理

create：./bin/epadmin create pub 启动建库向导（flavour 参数必填，实测不传或传非法值回显 Available repository types are: ... 并要求 Usage: epadmin create [repository type]）。24 问逐答全流程实录见安装篇第六节，此处不重复。

create_db / create_tables：向导拆步版——create_db <id> 按当前 database.pl 建库建用户，create_tables <id> 建表。实测建表回显形态：

Creating database tables ...
Set DB compatibility flag to '3.3.4'.
Done creating database tables.

create_user：建首个管理员/编辑的命令行入口。参数序（源码 bin/epadmin sub create_user 实测）：create_user <repo> <username> <usertype> <password> <email>，usertype 合法值 user/editor/admin（定义于 lib/namedsets/user）。实测新建一名编辑：

# ./bin/epadmin create_user demo tester editor q1w2e3r4 tester@eprints.qzuo.local
Creating a new user in demo


Successfully created new user:
  ID: 2

四、配置体检与热重载

test：配置与数据库连通性体检，实测回显：

# ./bin/epadmin test demo
Everything seems OK.

不传 archive id 则逐个加载全部库检查；加 --verbose 输出更多。

config_core / config_db：重跑建库向导的核心配置/数据库配置问答段（10_core.pl/database.pl 可再生成，文件头注释原文："You can regenerate this file by doing ./bin/epadmin config_core demo"）。

reload：通知 Web 进程重载配置，实测回显：

# ./bin/epadmin reload demo
The repository config will be reloaded, but you should still restart apache as
soon as possible.

set_developer_mode：epadmin set_developer_mode <id> on|off——on 时每个页面请求都重载配置，开发提效利器；--help 原文警告生产禁用（服务器负载剧增）。

五、索引与缓存维护

reindex：重建某 dataset 的检索索引。不带 dataset 参数实测直接落回 usage 帮助页；正确用法 reindex <repo> <dataset> [id...]，实测交互：

# ./bin/epadmin reindex demo eprint
You are about to reindex "eprint" in the demo repository.
This can take some time.

Number of records in set: 1
Continue [y/n] ?

管道场景加 --force 免确认。dataset 可取 eprint/document 等；对 eprint/document 加 --force 时 --help 原文注明会先重生成 .indexcodes 缓存再索引。

erase_fulltext_index：清空 .words/.indexcodes 缓存，强制全文抽取工具链（pdftotext/lynx 等）重跑——--help 原文场景：全文索引配置晚于建库启用、或抽取曾出错。

rebuild_triples：重排队 RDF 三元组缓存（可指定 dataset 与 dataobj id 列表/区间 10-20）；recommit：重算自动值（automatic fields）；reorder：重生成 order 排序值；redo_hash / rehash / redo_mime_type：重算文件哈希/校验和日志、重识别 MIME 类型；redo_thumbnails：重生成缩略图与图像预览。

refresh_views / refresh_abstracts / refresh_citations：通知 Web 进程重刷视图页/摘要列表页/引用缓存，--help 原文注明三者均附带 config reload。

cleanup_cachemaps：清理孤儿缓存表。

schema：为 EP3 XML 生成 schema——实测本环境失败（3.4.7 源码树缺插件，实录照抄）：

# ./bin/epadmin schema demo
Plugin 'Export::XML_Schema' not found.
Can't call method "initialise_fh" on an undefined value at ./bin/epadmin line 2373.

结论：该子命令依赖 Export::XML_Schema 插件，源码 tarball 未随附，需要时另行获取或改用官方 wiki 的 XSD。

六、用户会话管理

logout_all_users：epadmin logout_all_users <repo> [exclude_user_id ...] 强制全库下线（可豁免指定 uid），改权限/修漏洞后的止血动作。

七、结构同步与升级

典型链路：改 eprint_fields.pl 加字段 → epadmin update demo →（新字段有数据后）epadmin reindex demo eprint。

八、高危命令（实测环境刻意未执行）

• erase_data <id>：--help 原文——删库重建+清除所有文档与文件，不动配置文件；
• erase_eprints <id>：清空 eprint/document 表与文件，保留配置、用户与主题表；
• remove_field <id> <dataset> <field_id>：删除字段的数据库条目，原文警告 "can not be undone!"。

三者不可逆，本篇所在实测环境承载验证数据，故仅收录语义不演示执行。误删字段的恢复路径：改回配置 → update 无法找回已删列数据，只能重导入。

九、bin/import 与 bin/export：导入导出

usage 实测原文：

# ./bin/import
Usage:
    import repository_id [options] dataset

    import repository_id [options] dataset plugin filename

# ./bin/export
Usage:
    export repository_id [options] dataset

    export repository_id [options] dataset plugin [objectid] [objectid...]

要点：参数顺序 repo → dataset → plugin → filename/objectid；插件名大小写敏感（小写 bibtex 实测报 Plugin not found，正确为 BibTeX；EP3 XML 为 EPrintsXML，另有 Core/Csv/EndNote/DublinCore 等，界面导出下拉实测可见 Text/BibTeX/DC/EndNote/HTML/METS/Ids/OpenURL/Refer/RIS 十种）。

导入实测（--force 免逐条确认，--user 1 以 admin 身份）：

# ./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.

注意 warning 行：BibTeX 无状态字段，导入默认落 buffer（待审），发布需走 move_to_archive（第十二节）或后台审核。

导出实测：

# ./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.

不带 objectid 则导出全库；--verbose 打印连接与进度行。

十、bin/epindexer：索引守护

源码 tarball 的 bin/epindexer 是未替换占位符的模板（与 bin/epindexer.in 并存），直接运行报 No such file or directory 类路径错，实测修复：

sed -i "s|EPRINTS_PATH|/opt/eprints3|g" bin/epindexer
./bin/epindexer start
./bin/epindexer status

status 实测回显：

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

工作日志 /opt/eprints3/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!

索引器轮询 archives/<id>/var/last_changed.timestamp，记录变更后 30 秒级增量入库；Xapian 索引文件在 archives/<id>/var/xapian/。

十一、生成类工具

十二、API 脚本：CLI 覆盖不到的操作

EPrints 的 Perl API 可直接脚本化操作记录。实测范例——把 buffer 记录发布到 archive（set_archive.pl）：

#!/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;

发布后状态实测（get_value("eprint_status")）：

eprint 1 eprint_status = archive

两个实测教训：① API 没有 set_status/reindex 方法，状态迁移用 move_to_archive（buffer/deletion→archive）等专用动词；② EPrints::DataObj::EPrint 实例上直接调 get_status 实测报 Can't locate object method "get_status"——读字段值用 get_value("eprint_status")。脚本须以 eprints 用户执行（同一身份铁律）。

十三、日志与 var 目录

实测两级 var：

# ls /opt/eprints3/var/
indexer.log  indexer.pid  indexer.tick

# ls /opt/eprints3/archives/demo/var/
last_changed.timestamp  xapian

站点级：索引器日志/PID/tick；档案级：变更时间戳与 Xapian 索引。Apache 侧错误仍看系统日志（/var/log/apache2/error.log），mod_perl 阶段报错（如配置 Perl 语法错）都落在那里。

十四、CLI 常见问题速查

十五、参考链接

1. EPrints GitHub 仓库（bin/epadmin 源码与 pod 帮助）：https://github.com/eprints/eprints （查询日期 2026-11-01）
2. EPrints wiki 管理工具文档：https://wiki.eprints.org/w/EPrints_Admin （查询日期 2026-11-01）
3. EPrints API 参考（EPrints::DataObj::EPrint）：https://wiki.eprints.org/w/Category:API （查询日期 2026-11-01）
4. OAI-PMH 2.0 规范（导入导出互操作背景）：https://www.openarchives.org/OAI/openarchivesprotocol.html （查询日期 2026-11-01）
5. 站内姊妹篇：《EPrints 介绍与选型指南》、《EPrints 3.4.7 Ubuntu 22.04 安装部署指南》、《EPrints 配置参数详解（cfg.d 分层体系与关键项）》