---
title: "URL 仓库允许地址配置"
date: 2026-01-19
lastmod: 2026-01-19
description: "repositories.url.allowed_urls 配置项用于控制 URL 仓库可以访问的地址白名单。"
tags: ["Repositories", "快照", "URL", "安全配置"]
summary: "配置项作用 #  repositories.url.allowed_urls 配置项用于控制URL 仓库可以访问的地址白名单。
当使用 URL 类型的快照仓库时，此配置提供了一个安全机制，限制仓库只能访问指定的 URL 模式，防止未经授权的 URL 访问。
配置项属性 #   配置路径: repositories.url.allowed_urls 数据类型: List<URIPattern>（URL 模式列表） 默认值: 空列表（不允许任何 URL） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  URL 白名单机制 创建 URL 仓库时: URL: http://backup.example.com/snapshots │ ├── 检查 allowed_urls │ ├── 匹配白名单? │ │ ├── 是 → 允许访问 ✅ │ │ └── 否 → 继续 │ └── ... │ ├── 检查 path."
---


## 配置项作用

`repositories.url.allowed_urls` 配置项用于控制**URL 仓库可以访问的地址白名单**。

当使用 URL 类型的快照仓库时，此配置提供了一个安全机制，限制仓库只能访问指定的 URL 模式，防止未经授权的 URL 访问。

## 配置项属性

- **配置路径**: `repositories.url.allowed_urls`
- **数据类型**: `List<URIPattern>`（URL 模式列表）
- **默认值**: 空列表（不允许任何 URL）
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: **否**（需要重启节点生效）

## 配置项详解

## 工作机制

```
URL 白名单机制

创建 URL 仓库时:
URL: http://backup.example.com/snapshots
    │
    ├── 检查 allowed_urls
    │   ├── 匹配白名单?
    │   │   ├── 是 → 允许访问 ✅
    │   │   └── 否 → 继续
    │   └── ...
    │
    ├── 检查 path.repo
    │   ├── 匹配本地路径?
    │   │   ├── 是 → 允许访问 ✅
    │   │   └── 否 → 拒绝 ❌
    └── ...
    │
    └── 都不匹配 → 拒绝访问 ❌


安全层:
├── allowed_urls: URL 白名单
├── path.repo: 本地路径白名单
└── 双重保护 ✅
```

## 模式匹配语法

```
URL 模式匹配

通配符支持 *:


http://example.com/*
├── 匹配: http://example.com/任何路径
└── 示例: http://example.com/snapshots/*


http://*.local/*
├── 匹配: http://任何.local/任何路径
├── 示例: http://server.local/snapshots/
└── 示例: http://backup.local/data/


file:///data/backups/*
├── 匹配: file:///data/backups/任何路径
├── 本地文件系统
└── 示例: file:///data/backups/snap1/


ftp://server.local/snapshots/*
├── 匹配: FTP 服务器路径
├── FTP 协议
└── 示例: ftp://server.local/snapshots/file1


* (所有 URL):
├── 匹配: 任何 URL
├── 危险配置 ⚠️
└── 不推荐生产使用
```

## 协议支持

```
支持的协议

默认支持协议:
├── http
├── https
├── ftp
├── file
└── jar


配置示例:
allowed_urls:
  - "http://backup.example.com/*"
  - "https://secure.backup.com/*"
  - "file:///data/backups/*"
  - "ftp://ftp.server.local/*"


协议说明:
├── http: 超文本传输
├── https: 加密传输
├── ftp: 文件传输协议
├── file: 本地文件系统
└── jar: JAR 文件内
```

## 配置建议

## 生产环境（严格限制）

```yaml
# easysearch.yml
repositories:
  url:
    allowed_urls:
      - "https://backup.example.com/snapshots/*"
      - "https://dr.backup.example.com/*"
```

**建议**: 明确指定允许的 URL，使用 HTTPS。

## 开发环境（本地文件）

```yaml
repositories:
  url:
    allowed_urls:
      - "file:///data/backups/*"
```

**建议**: 开发环境可以使用本地文件路径。

## FTP 仓库

```yaml
repositories:
  url:
    allowed_urls:
      - "ftp://ftp.server.local/snapshots/*"
```

**建议**: 使用 FTP 时确保连接安全。

## 测试环境

```yaml
repositories:
  url:
    allowed_urls:
      - "*"
```

**建议**: 仅测试环境使用 `*`，生产环境禁止。

## 代码示例

## 创建 URL 仓库

```json
PUT /_snapshot/url_backup
{
  "type": "url",
  "settings": {
    "url": "http://backup.example.com/snapshots"
  }
}
```

## 配置白名单

```yaml
# easysearch.yml
repositories:
  url:
    allowed_urls:
      - "http://backup.example.com/*"
      - "https://backup.example.com/*"
```

## 完整配置

```yaml
# easysearch.yml
repositories:
  url:
    allowed_urls:
      - "https://primary.backup.com/snapshots/*"
      - "https://secondary.backup.com/snapshots/*"
      - "file:///mnt/backup/snapshots/*"
```

## 多个 URL 仓库

```json
// 仓库 1
PUT /_snapshot/backup1
{
  "type": "url",
  "settings": {
    "url": "https://backup1.example.com/snapshots"
  }
}

// 仓库 2
PUT /_snapshot/backup2
{
  "type": "url",
  "settings": {
    "url": "https://backup2.example.com/snapshots"
  }
}
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `allowed_urls` | URL 白名单 | 空列表 |
| `url` | 仓库 URL | 必须配置 |
| `supported_protocols` | 支持的协议 | http, https, ftp, file, jar |

## 安全建议

```
安全配置建议

1. 使用 HTTPS
   allowed_urls:
     - "https://backup.example.com/*"

   ├── 加密传输 ✅
   ├── 数据保护
   └── 推荐 ✅


2. 明确指定域名
   allowed_urls:
     - "https://backup.example.com/snapshots/*"
     - "https://dr.backup.example.com/snapshots/*"

   ├── 限制域名 ✅
   ├── 避免通配符
   └── 生产环境 ✅


3. 限制路径
   allowed_urls:
     - "https://backup.example.com/snapshots/*"

   ├── 限制路径范围 ✅
   ├── 细粒度控制
   └── 安全增强


4. 禁止所有通配符
   ❌ "http://*"
   ❌ "https://*"
   ❌ "*"

   ├── 过于宽松
   ├── 安全风险
   └── 生产禁止 ❌


5. 定期审查
   ├── 审查白名单
   ├── 移除不需要的
   ├── 添加新需要的
   └── 最小权限原则
```

## 故障排查

```
常见问题排查

问题 1: URL 被拒绝

错误:
URL is not in whitelist


检查:
├── allowed_urls 配置
├── URL 格式
├── 协议是否支持
└── 路径是否匹配


解决:
├── 添加 URL 到白名单
├── 检查通配符匹配
├── 使用正确的协议
└── 重启节点


问题 2: 配置不生效

检查:
├── 配置文件位置
├── 配置格式
├── 是否重启
└── 语法错误


解决:
├── 验证配置文件
├── 检查 YAML 语法
├── 重启节点
└── 验证配置


问题 3: 协议不支持

错误:
protocol not supported


检查:
├── URL 协议
├── supported_protocols
└── 插件安装


解决:
├── 使用支持的协议
├── 安装必要的插件
└── 或更改 URL 格式
```

## 最佳实践

```
安全配置最佳实践

1. 生产环境
   allowed_urls:
     - "https://backup.company.com/snapshots/*"
     - "https://dr.backup.company.com/snapshots/*"

   ├── 仅 HTTPS ✅
   ├── 明确域名
   ├── 限制路径
   └── 最小权限 ✅


2. 开发环境
   allowed_urls:
     - "file:///data/backups/*"

   ├── 本地文件
   ├── 无网络风险
   └── 便于测试


3. 多环境
   allowed_urls:
     - "https://prod-backup.com/*"
     - "https://staging-backup.com/*"

   ├── 环境隔离
   ├── 明确区分
   └── 安全隔离


4. 定期审查
   ├── 每季度审查
   ├── 移除过期的
   ├── 添加新需要的
   └── 文档记录


5. 应急预案
   ├── 快速添加新 URL
   ├── 紧急时临时开放
   ├── 事后清理
   └── 审计日志
```