---
title: "NocoBase 安全指南"
description: "NocoBase 安全指南：用户认证、JWT Token 策略、APP_KEY、访问控制、数据加密、IP 限制、密码策略、审计日志、LocalStorage/SessionStorage 存储。"
keywords: "NocoBase 安全,用户认证,Token 策略,访问控制,数据加密,IP 限制,密码策略,审计日志,NocoBase"
---

# NocoBase 安全指南

NocoBase 从功能设计到系统实现都注重数据和应用的安全性。平台内置了用户认证、访问控制、数据加密等多项安全功能，同时允许根据实际需求灵活配置安全策略。无论是保护用户数据、管理访问权限，还是隔离开发和生产环境，NocoBase 都提供了实用的工具和方案。本指南旨在为安全地使用 NocoBase 提供指导，帮助用户保护数据、应用和环境的安全，确保用户安全的前提下高效使用系统功能。

## 用户认证

用户认证用于识别用户身份，防止用户在未授权的情况下进入系统，并确保用户身份不被滥用。

### Token 密钥

默认情况下，NocoBase 使用 JWT (JSON Web Token) 对服务端 API 进行鉴权。用户可以通过系统环境变量 `APP_KEY` 设置 Token 的密钥，请妥善管理应用的 Token 密钥，防止对外泄漏。需要注意的是，如果 `APP_KEY` 修改了，旧的 Token 也会随之失效。

### Token 策略

NocoBase 支持对用户 Token 设置以下安全策略：

| 配置项              | 说明                                                                                                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 会话有效期          | 用户每次登录的最长有效时间，在会话有效期内，Token 会自动更新，超时后要求用户重新登录。                                                                                                |
| Token 有效期        | 每次签发的 API Token 的有效期。Token 过期后，如果处于会话有效期内，并且没有超过刷新时限，服务端将自动签发新 Token 以保持用户会话，否则要求用户重新登录。（每个 Token 只能被刷新一次） |
| 过期 Token 刷新时限 | Token 过期后允许刷新的最大时限                                                                                                                                                        |

通常情况下，我们建议管理员：

- 设置一个较短的 Token 有效期来限制 Token 的暴露时间。
- 设置一个合理的会话有效期，比 Token 有效期长但不宜过长，以平衡用户体验和安全性。利用 Token 自动刷新的机制保证活跃用户会话不中断的同时，减少长期会话被滥用的风险。
- 设置一个合理的过期 Token 刷新时限，使用户长时间不活跃的情况下 Token 自然过期而不签发新的 Token, 降低用户闲置会话被滥用的风险。

### Token 客户端存储

默认情况下，用户 Token 存储在浏览器的 LocalStorage 中。关闭浏览器页面后再次打开，如果 Token 还在有效期内，用户不需要重新登录。

如果你希望用户每次进入页面都需要重新登录，可以设置环境变量 `API_CLIENT_STORAGE_TYPE=sessionStorage`, 将用户 Token 保存到浏览器的 SessionStorage 中，以达到用户每次打开页面重新登录的目的。

### 密码策略

> 专业版及以上

NocoBase 支持为所有用户设置密码规则和密码登录尝试锁定策略，来增强启用了密码登录的 NocoBase 应用的安全性。你可以参考[密码策略](./password-policy/index.md)了解每一个配置项。

#### 密码规则

| 配置项                     | 说明                                                     |
| -------------------------- | -------------------------------------------------------- |
| **密码长度**               | 密码的最小长度要求，最大长度为 64。                      |
| **密码复杂度**             | 设置密码的复杂度要求，必须包含的字符种类。               |
| **不能在密码中包含用户名** | 设置密码是否能包含当前用户的用户名。                     |
| **记住密码历史**           | 记住用户最近使用的密码个数，用户修改密码时不能重复使用。 |

#### 密码过期配置

| 配置项                   | 说明                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **密码有效期**           | 用户密码的有效期。用户必须在密码过期前更换密码，才会重新计算有效期。若未在过期前更换密码，将无法使用旧密码登录，需管理员协助重置。<br>如果有配置其他的登录方式，用户可以使用其他方式登录。 |
| **密码过期提示通知渠道** | 用户密码到期的 10 天内，用户每次登录时，发送提醒。                                                                                                                                         |

#### 密码登录安全

| 配置项                             | 说明                                                                                                                                |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **最大无效密码登录尝试次数**       | 设置用户在规定时间间隔内最多可以尝试登录次数。                                                                                      |
| **最大无效密码登录时间间隔（秒）** | 设置计算用户最大无效登录次数的时间间隔，单位为秒。                                                                                  |
| **锁定时间（秒）**                 | 设置用户超过无效密码登录限制以后，锁定用户的时间（0 代表不限制）。<br>用户被锁定期间，将禁止以任何认证方式访问系统，包括 API keys。 |

通常情况下，我们建议：

- 设置强度较高的密码规则，以降低密码被关联性猜测、暴力破解的风险。
- 设置合理的密码有效期，以强制用户定期更换密码。
- 结合无效密码登录次数和时间配置，限制短时间内高频的密码登录尝试，防止暴力破解密码的行为。
- 如果在安全要求比较严格的场景下，可以设置一个合理的超过登录限制锁定用户的时间。但需要注意的是，锁定时间设置可能被恶意利用，攻击者可能针对目标账号故意多次输入错误密码，迫使账号被锁定，无法正常使用。实际使用过程中，可以结合 IP 限制，API 频率限制等手段来防范这类攻击。
- 修改 NocoBase 默认的 root 用户名、邮箱、密码，避免被恶意利用。
- 由于密码过期或账号锁定都将无法进入系统，包括管理员账号，建议在系统中设置多个有权限重置密码、解锁用户的账号。

![](https://static-docs.nocobase.com/202501031618900.png)

### 用户锁定

> 专业版及以上，包含在密码策略插件中

管理因为超过无效密码登录限制而被锁定的用户，可以主动解锁，也可以主动将异常用户添加到锁定列表。用户被锁定后，将禁止以任何认证方式访问系统，包括 API keys.

![](https://static-docs.nocobase.com/202501031618399.png)

### API 密钥

NocoBase 支持通过 API 密钥的方式调用系统 API, 用户可以在 API 密钥插件配置中添加 API 密钥。

- 请为 API 密钥绑定正确的角色，并确保与角色相关联的权限正确配置。
- 在使用 API 密钥的过程中，防止 API 密钥对外泄漏。
- 通常情况下，我们建议用户为 API 密钥设置一个有效期限，不使用“永不过期”选项。
- 如果发现 API 密钥被异常使用，可能有泄漏风险，用户可以删除对应的 API 密钥，使其失效。

![](https://static-docs.nocobase.com/46141872fc0ad9a96fa5b14e97fcba12.png)

### 单点登录 (Single Sign-On)

> 商业插件

NocoBase 提供了丰富的 SSO 认证插件，支持 OIDC, SAML 2.0, LDAP, CAS 等多种主流协议。同时，NocoBase 也有完备的认证方式扩展接口，可以支持快速开发和接入其他认证类型。可以简单地将已有 IdP 和 NocoBase 对接，在 IdP 上集中管理用户身份，提高安全性。
![](https://static-docs.nocobase.com/202501031619427.png)

### 双因素身份认证 (Two-factor authentication)

> 企业版

双因素身份认证要求用户在使用密码登录的时候，提供第二种证明身份的有效信息，例如通过向用户的可信设备发送一次性动态验证码，以验证用户身份，确保用户身份不被滥用，降低密码泄露产生的风险。

### IP 访问控制

> 企业版

NocoBase 支持对用户访问 IP 设置黑名单或白名单。

- 在安全要求严格的环境中，可以设置 IP 白名单，仅允许特定 IP 或 IP 段访问系统，以限制未授权的外部网络连接，从源头降低安全风险。
- 在公开的网络访问条件下，如果管理员发现访问异常，可以设置 IP 黑名单，阻止已知的恶意 IP 地址，或可疑来源的访问，减少恶意扫描、暴力破解等安全威胁。
- 对被拒绝的访问请求，保留日志记录。

## 权限控制

通过在系统中设置不同的角色，以及对角色设置相应的权限，可以精细化地控制用户访问资源的权限。管理员需要结合实际场景需要，合理配置，以降低系统资源泄漏的风险。

### Root 用户

在初次安装 NocoBase 的时候，应用会初始化一个 root 用户。建议用户通过设置系统环境变量修改 root 用户的相关信息，避免被恶意利用。

- `INIT_ROOT_USERNAME` - root 用户名
- `INIT_ROOT_EMAIL` - root 用户邮箱
- `INIT_ROOT_PASSWORD` - root 用户密码，请设置一个高强度的密码。

在后续使用系统的过程中，建议用户设置并使用其他管理员账号，尽量避免直接使用 root 用户操作应用。

### 角色和权限

NocoBase 通过在系统中设置角色，对不同角色授权，并将用户绑定到对应的角色上来控制用户访问资源的权限。每个用户可以拥有多个角色，用户可以通过切换角色，以不同的视角来操作资源。如果安装了部门插件，还可以将角色和部门绑定，用户就可以拥有所属部门上绑定的角色。

![](https://static-docs.nocobase.com/202501031620965.png)

### 系统配置权限

系统配置权限包含了以下设置：

- 是否允许配置界面
- 是否允许安装、启用、禁用插件
- 是否允许配置插件
- 是否允许清除缓存、重启应用
- 各个插件的配置权限

### 菜单权限

菜单权限用于控制用户进入不同菜单页面的权限，包括桌面端和移动端。
![](https://static-docs.nocobase.com/202501031620717.png)

### 数据权限

NocoBase 为用户访问系统内数据的权限提供了精细化的控制，确保不同用户只能访问与其职责相关的数据，防止越权和数据泄露。

#### 全局控制

![](https://static-docs.nocobase.com/202501031620866.png)

#### 表级别、字段级别控制

![](https://static-docs.nocobase.com/202501031621047.png)

#### 数据范围控制

设置用户可操作的数据范围。注意此处的数据范围和区块中配置的数据范围不同，区块中配置的数据范围通常仅做前端过滤数据使用，如果需要严格控制用户访问数据资源的权限，需要在此处配置，由服务端控制。

![](https://static-docs.nocobase.com/202501031621712.png)

## 数据安全

在数据存储、备份的过程中，NocoBase 提供了有效的机制，来确保数据安全。

### 密码存储

NocoBase 的用户密码使用 scrypt 算法加密后存储，可以有效对抗大规模的硬件攻击。

### 环境变量和密钥

在 NocoBase 中使用第三方服务的时候，我们推荐你将第三方的密钥信息配置到环境变量中，加密存储。既方便在不同的地方配置使用，又增强了的安全性。你可以查看文档了解详细的使用方法。

:::warning
默认情况下，密钥采用 AES-256-CBC 算法加密，NocoBase 会自动生成 32 位加密密钥并保存到 storage/.data/environment/aes_key.dat. 用户应该妥善保管密钥文件，防止密钥文件被窃取。如果需要迁移数据，密钥文件需要一并迁移。
:::

![](https://static-docs.nocobase.com/202501031622612.png)

### 文件存储

如果有存储敏感文件的需要，建议使用兼容 S3 协议的云存储服务，并配合商业版插件 File storage: S3 (Pro) ，实现文件的私有读写。如果需要在内网环境使用，建议使用 MinIO 等支持私有化部署、兼容 S3 协议的存储应用。

![](https://static-docs.nocobase.com/202501031623549.png)

对于本地存储或其他可通过应用同源 URL 直接访问的 public 存储，还需要额外注意“主动内容文件”带来的风险。例如 `html`、`xhtml`、`svg` 等文件可能在浏览器中被直接解析和执行。如果攻击者能够上传此类文件，并诱导用户打开文件链接，就可能借助应用的可信域名承载恶意页面或脚本。

通常情况下，我们建议管理员：

- 优先使用私有存储、签名 URL，或独立文件域名，避免用户上传文件与应用主站同源直接访问。
- 对上传文件启用严格的 MIME type 白名单，仅允许业务实际需要的文件类型。
- 谨慎允许 `text/html`、`application/xhtml+xml`、`image/svg+xml` 等主动内容类型上传。即使系统会对这类文件尽量采用下载方式返回，也不应将其视为可替代上传限制和访问隔离的完整防护。
- 对外部反向代理、CDN、对象存储等静态文件分发层进行一致的安全配置，避免绕过应用层策略直接以内联方式返回危险文件。
- 不要把本地/public 存储用于托管不受信任的网页内容；如确有此类需求，应使用隔离域名，并单独评估 CSP、下载策略和访问控制。

如果管理员显式放开危险文件类型上传，应自行评估由此带来的钓鱼、同源脚本执行、敏感信息泄露等风险，并确保部署链路中的 Web Server、网关、CDN 和存储服务采取一致的限制策略。

### 应用备份

为了确保应用数据安全，避免数据丢失，我们建议你定期备份数据库。

开源版用户可以参考 https://www.nocobase.com/en/blog/nocobase-backup-restore 利用数据库工具进行备份，同时我们建议你妥善保管好备份文件，防止数据泄漏。

专业版及以上用户可以使用备份管理器进行备份，备份管理器提供了以下特性：

- 定时自动备份：周期性自动备份，节省时间和人工操作，数据安全更有保障。
- 将备份文件同步到云存储：将备份文件和应用服务本身隔离，防止因服务器故障导致服务不可用的同时备份文件丢失。
- 备份文件加密：给备份文件设置密码，降低备份文件泄漏导致数据泄漏的风险。

![](https://static-docs.nocobase.com/202501031623107.png)

## 运行环境安全

正确部署 NocoBase 并保障运行环境安全，是确保 NocoBase 应用安全的关键之一。

### HTTPS 部署

为了防止中间人攻击，我们建议你为 NocoBase 应用站点添加 SSL/TLS 证书，以保障数据在网络传输过程中的安全。

### API 传输加密

> 企业版

在数据安全要求更为严格的环境中，NocoBase 支持启用 API 传输加密，为 API 的请求和响应内容加密，避免明文传输，提高数据破解的门槛。

### 私有化部署

默认情况下，NocoBase 不需要与第三方服务通信，NocoBase 团队不会收集用户的一切信息。只有在执行以下两种操作时需要连接 NocoBase 服务器：

1. 通过 NocoBase Service 平台自动下载商业插件。
2. 在线验证和激活商业版应用。

如果你愿意牺牲一定的便利性，这两种操作也都支持离线完成，不需要直接连接 NocoBase 服务器。

NocoBase 支持完全内网部署，参考

- https://www.nocobase.com/en/blog/load-docker-image

### 多环境隔离

> 专业版及以上

在实际的使用实践中，我们推荐企业用户将测试和生产环境隔离，以确保生产环境下的应用数据和运行环境安全。利用迁移管理插件，可以实现应用数据在不同环境之间迁移。

![](https://static-docs.nocobase.com/202501031627729.png)

## 审计和监控

### 审计日志

> 企业版

NocoBase 的审计日志功能记录了系统内用户的活动记录。通过记录用户的关键操作和访问行为，管理员可以：

- 检查用户访问的 IP, 设备等信息，以及操作时间，及时发现异常行为。
- 追溯系统内数据资源的操作历史。

![](https://static-docs.nocobase.com/202501031627719.png)

![](https://static-docs.nocobase.com/202501031627922.png)

### 应用日志

NocoBase 提供多种日志类型，帮助用户了解系统运行状况和行为记录，及时发现和定位系统问题，从不同维度保障系统的安全性和可控性。主要日志类型包括：

- 请求日志：API 请求日志，包括访问的 URL、HTTP 方法、请求参数、响应时间和状态码等信息。
- 系统日志：记录应用运行事件，包括服务启动、配置变更、错误信息和关键操作等。
- SQL 日志：记录数据库操作语句及其执行时间，涵盖查询、更新、插入和删除等行为。
- 工作流日志：工作流的执行日志，包括执行时间、运行信息、错误信息等。
