ukwa/outbackcdx

OutbackCDX（原tinycdxserver）

基于RocksDB的网络档案捕获索引（CDX）服务器。

• https://nla.github.io/outbackcdx/api.html

核心功能与特性

• 支持https://github.com/iipc/openwayback/%EF%BC%88XML%EF%BC%89%E5%92%8Chttps://github.com/webrecorder/pywb%EF%BC%88JSON%EF%BC%89%E4%B8%A4%E7%A7%8DCDX%E5%8D%8F%E8%AE%AE
• 实时增量更新
• 压缩索引（varint压缩+snappy），通常为CDX文件大小的1/4-1/5
• 主从复制
• 访问控制（实验性，详见下文）

暂不支持的功能

• 分片、复制
• CDXJ

使用场景与适用范围

已在澳大利亚国家图书馆和大英图书馆的生产环境中使用，处理80-90亿条记录的索引。

使用方法与配置说明

构建

bash
mvn package

运行

bash
java -jar target/outbackcdx*.jar

命令行选项

Usage: java -jar outbackcdx.jar [options...]

  -b bindaddr           绑定到特定IP地址
  -c, --context-path url-prefix
                        设置应用程序挂载的URL前缀
  -d datadir            存储索引数据的目录
  -i                    通过STDIN继承服务器套接字（用于systemd、inetd等）
  -j jwks-url perm-path 使用JSON Web Tokens进行授权
  -k url realm clientid 使用Keycloak服务器进行授权
  -m max-open-files     限制打开的.sst文件数量以控制内存使用
                        （默认值396，基于系统内存和ulimit -n）
  -p port               监听的本地端口
  -t count              Web服务器线程数
  -r count              为单个请求扫描的rocksdb记录数量上限
  -x                    默认输出CDX14（而非CDX11）
  -v                    详细日志
  -y file               自定义模糊匹配规范化YAML配置文件

主模式（作为下游从节点的复制目标运行）
  --replication-window interval      从磁盘删除复制历史的时间间隔（秒）。
                                     0禁用自动删除。可通过向/<collection>/truncate_replication
                                     POST复制序列号手动删除历史文件

从模式（只读运行；轮询上游服务器的'collection-url'获取变更）
  --primary collection-url           上游主节点上集合的轮询URL
  --update-interval poll-interval    上游变更的轮询频率（秒）。默认：10
  --accept-writes                    允许写入此节点，即使作为从节点运行
  --batch-size                       每个复制批次的近似最大大小（字节）

服务器支持多个命名索引作为子目录。目前，首次写入记录时会自动创建索引。

加载记录

OutbackCDX不包含用于读取WARC或ARC文件的CDX索引工具。使用OpenWayback或PyWb附带的cdx-indexer脚本。

可通过POST Wayback使用的（11字段）CDX格式记录来加载索引：

bash
$ cdx-indexer mycrawlw.warc.gz > records.cdx
$ curl -X POST --data-binary @records.cdx http://localhost:8080/myindex
Added 542 records

规范化URL（第一个字段）会被忽略，OutbackCDX会执行自己的规范化。

限制：在一个POST请求中加载极大量CDX记录可能导致https://github.com/nla/outbackcdx/issues/13%E3%80%82%E4%BF%AE%E5%A4%8D%E5%89%8D%E5%8F%AF%E8%83%BD%E9%9C%80%E8%A6%81%E5%B0%86%E8%AF%B7%E6%B1%82%E6%8B%86%E5%88%86%E4%B8%BA%E5%A4%9A%E4%B8%AA%E8%BE%83%E5%B0%8F%E8%AF%B7%E6%B1%82%E3%80%82%E5%A4%A7%E5%A4%9A%E6%95%B0%E7%94%A8%E6%88%B7%E6%AF%8F%E4%B8%AAWARC%E6%96%87%E4%BB%B6%E5%8F%91%E9%80%81%E4%B8%80%E4%B8%AAPOST%E3%80%82

删除记录

删除记录的操作与加载类似。将待删除记录POST到/{collection}/delete：

bash
$ curl -X POST --data-binary @records.cdx http://localhost:8080/myindex/delete
Deleted 542 records

删除时OutbackCDX不检查记录是否实际存在于索引中。删除不存在的记录无效果且不会导致错误。

查询

可按CDX格式查询记录：

bash
$ curl 'http://localhost:8080/myindex?url=example.org'
org,example)/ 20030402160014 http://example.org/ text/html 200 MOH7IEN2JAEJOHYXIEPEEGHOHG5VI=== - - 2248 396 mycrawl.warc.gz

JSON数组格式的CDX：

bash
$ curl 'http://localhost:8080/myindex?url=example.org&output=json'
[
  [
    "org,example)/",
    20030402160014,
    "http://example.org/",
    "text/html",
    200,
    "MOH7IEN2JAEJOHYXIEPEEGHOHG5VI===",
    2248,
    396,
    "mycrawl.warc.gz"
  ]
]

OpenWayback "OpenSearch" XML：

bash
$ curl 'http://localhost:8080/myindex?q=type:urlquery+url:http%3A%2F%2Fexample.org%2F'
<?xml version="1.0" encoding="UTF-8"?>
<wayback>
   <request>
       <startdate>19960101000000</startdate>
       <enddate>20180526162512</enddate>
       <type>urlquery</type>
       <firstreturned>0</firstreturned>
       <url>org,example)/</url>
       <resultsrequested>10000</resultsrequested>
       <resultstype>resultstypecapture</resultstype>
   </request>
   <results>
       <result>
           <compressedoffset>396</compressedoffset>
           <compressedendoffset>2248</compressedendoffset>
           <mimetype>text/html</mimetype>
           <file>mycrawl.warc.gz</file>
           <redirecturl>-</redirecturl>
           <urlkey>org,example)/</urlkey>
           <digest>MOH7IEN2JAEJOHYXIEPEEGHOHG5VI===</digest>
           <httpresponsecode>200</httpresponsecode>
           <robotflags>-</robotflags>
           <url>http://example.org/</url>
           <capturedate>20030402160014</capturedate>
       </result>
   </results>
</wayback>

查询匹配给定URL前缀的URL：

bash
$ curl 'http://localhost:8080/myindex?url=http://example.org/abc&matchType=prefix'

查找给定域名的前5个URL：

bash
$ curl 'http://localhost:8080/myindex?url=example.org&matchType=domain&limit=5'

从给定URL前缀开始查找索引中的下10个URL：

bash
$ curl 'http://localhost:8080/myindex?url=http://example.org/abc&matchType=range&limit=10'

按反向顺序返回结果：

bash
$ curl 'http://localhost:8080/myindex?url=example.org&sort=reverse'

按与给定时间戳的接近程度排序返回结果（从近到远）：

bash
$ curl 'http://localhost:8080/myindex?url=example.org&sort=closest&closest=20030402172120'

有关可用选项的更多详细信息，请参见https://nla.github.io/outbackcdx/api.html%E3%80%82

配置回放工具

OpenWayback

通过配置RemoteResourceIndex将Wayback指向OutbackCDX索引。参见OpenWayback附带的示例RemoteCollection.xml。

xml
    <property name="resourceIndex">
      <bean class="org.archive.wayback.resourceindex.RemoteResourceIndex">
        <property name="searchUrlBase" value="http://localhost:8080/myindex" />
      </bean>
    </property>

PyWb

创建包含以下内容的pywb config.yaml文件：

yaml
collections:
  testcol:
    archive_paths: /tmp/warcs/
    #archive_paths: http://remote.example.org/warcs/
    index:
      type: cdx
      api_url: http://localhost:8080/myindex?url={url}&closest={closest}&sort=closest
    
      # outbackcdx不提供warc记录服务
      # 因此将replay_url设为空以强制pywb自行读取warc文件
      replay_url: ""

Heritrix

ukwa-heritrix项目包含https://github.com/ukwa/ukwa-heritrix/blob/21d31329065f2a6a68186309757a5644af00daec/src/main/java/uk/bl/wap/modules/uriuniqfilters/OutbackCDXRecentlySeenUriUniqFilter.java%EF%BC%8C%E5%85%81%E8%AE%B8%E5%B0%86OutbackCDX%E7%94%A8%E4%BD%9CHeritrix%E7%88%AC%E5%8F%96%E7%9A%84%E5%8E%BB%E9%87%8D%E6%95%B0%E6%8D%AE%E6%BA%90%E3%80%82

访问控制

可通过设置以下环境变量启用访问控制：

bash
EXPERIMENTAL_ACCESS_CONTROL=1

可通过GUI配置规则。让Wayback或其他客户端查询特定命名的访问点。例如，查询'public'访问点：

http://localhost:8080/myindex/ap/public

有关访问控制模型的详细信息，请参见docs/access-control.md。

规范化别名

别名记录允许对URL进行分组，使其表现为同一页面的不同快照。

@alias <源URL> <目标URL>

例如：

@alias http://legacy.example.org/page-one http://www.example.org/page1
@alias http://legacy.example.org/page-two http://www.example.org/page2

别名目前不适用于URL前缀查询。别名在应用常规规范化规则后解析。

别名可与常规CDX行混合在同一文件或单独文件中，顺序不限。添加别名到索引时，任何受别名规则影响其规范化URL的现有记录都会被更新。

别名删除功能尚未实现。

内存使用调优

RocksDB为每个打开的SST文件在内存中存储一些数据（二分查找索引、布隆过滤器）。这以增加内存使用为代价提高性能。OutbackCDX默认使用以下启发式方法限制打开的SST文件最大数量，以避免耗尽系统内存：

RocksDB max_open_files = (totalSystemRam / 2 - maxJvmHeap) / 10 MB

当使用多个大型索引或OutbackCDX与许多其他进程共享服务器时，此默认值可能不适用。可通过OutbackCDX的-m选项覆盖限制。

如果发现OutbackCDX内存使用过高或需要更高性能，可尝试调整此限制。最佳设置取决于索引大小和硬件。如果内存充足，-m -1（无限制）将允许RocksDB在启动时打开所有SST文件，并应提供最佳查询性能。但在慢速磁盘上，这也可能导致启动非常缓慢。可能还需要增加内核的最大打开文件描述符限制（ulimit -n）。

授权

默认情况下，OutbackCDX未受保护，假设使用防火墙规则或反向代理等外部方法进行授权。注意不要将其暴露到公共互联网。

或者，可启用以下授权方法之一。

通用JWT授权

可使用JSON Web Tokens控制修改索引和访问控制规则的授权。要启用此功能，通常需要使用某种单独的认证服务器来签名JWT。

OutbackCDX的-j选项接受两个参数：认证服务器公钥的JWKS URL，以及在作为HTTP bearer令牌接收的JWT中查找权限列表的斜杠分隔路径。有关使用方法，请参考认证服务器的文档。

目前，OutbackCDX Web仪表板不支持通用JWT/OIDC授权。（欢迎提交补丁。）

Keycloak授权

OutbackCDX可使用Keycloak作为认证服务器来保护API和仪表板。

1. 在Keycloak领域设置中为OutbackCDX创建新客户端，协议为openid-connect，URL为OutbackCDX实例的URL。
2. 在客户端的角色选项卡下创建以下角色：
   • index_edit - 可创建或删除索引记录
   • rules_edit - 可创建、修改或删除访问规则
   • policies_edit - 可创建、修改或删除访问策略
3. 适当地将用户或服务账户映射到这些客户端角色。
4. 使用以下选项运行OutbackCDX：

bash
-k https://{keycloak-server}/auth {realm} {client-id}

注意：使用Keycloak时会自动启用JWT认证。无需设置-j选项。

HMAC字段

OutbackCDX可配置为使用HMAC或加密摘要计算字段。此功能旨在与通过签名URL提供WARC文件临时访问的Web服务器或云存储提供商配合使用。为兼容各种存储服务器，消息结构和字段值通过模板配置。

--hmac-field name algorithm message-template field-template secret-key expiry-secs     

该字段将作为name提供给fl CDX查询参数。只要名称不同，可定义多个HMAC字段。

algorithm可以是HmacSHA256、HmacSHA1、HmacMD5、SHA-256、SHA-1、MD5或Java安全提供程序中的任何其他MAC或MessageDigest。根据Java的版本和配置，系统可能提供其他算法。

message-template配置HMAC或摘要函数的输入。参见下文的模板变量列表。

field-template配置返回的字段值，通常用于构造URL。参见下文的模板变量列表。

secret-key是HMAC函数的密钥。使用非HMAC摘要函数（无自然密钥参数）时，可使用$secret_value将密钥代入message-template。

expiry-secs参数用于计算此安全链接的过期时间。如果不使用$expires变量，只需将其设置为0。

模板变量

除每个捕获记录的字段（$filename、$length、$offset等）外，模板中还提供以下额外变量：

• $dollar - ***符号（"$"）
• $expires - 过期时间（Unix时间戳，秒）
• $expires_hex - 过期时间（十六进制Unix时间戳，秒）
• $expires_iso8601 - 过期时间（UTC ISO 8601时间戳）
• $hmac_base64 - 计算的hmac/digest值（base64字符串，仅在值模板中可用）
• $hmac_base64_pct - 计算的hmac/digest值（base64字符串，+编码为%2B）
• $hmac_base64_url - 计算的hmac/digest值（URL安全的base64字符串）
• $hmac_hex - 计算的hmac/digest值（十六进制字符串，仅在值模板中可用）
• $secret_key - 密钥（仅在消息模板中可用）
• $now - 当前时间（Unix时间戳，秒）
• $now_hex - 当前时间（十六进制Unix时间戳，秒）
• $now_iso8601 - 当前时间（UTC ISO 8601时间戳）
• $CR - 回车符（"\r"）
• $CRLF - 回车换行符（"\r\n"）
• $LF - 换行符（"\n"）

也可使用替代变量语法${filename}。

HMAC字段示例

nginx HTTP安全链接模块

注意：nginx附带的安全链接模块使用不安全的MD5算法。考虑使用社区开发的HMAC安全链接模块替代。

示例nginx配置：

nginx
location /warcs/ {
   secure_link $arg_md5,$arg_expires;
   secure_link_md5 "$secure_link_expires|$uri|$http_range|secret";
   if ($secure_link != "1") { return 403; }
   ...
}

对应的OutbackCDX选项：

bash
--hmac-field warcurl md5 '$expires|/warcs/$filename|$range|$secret_key'
     'http://nginx.example.org/warcs/$filename?expires=$expires&md5=$hmac_base64_url'
     secret 3600

[nginx HTTP HMAC安全链接