- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- module/typescript TS 模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
Node.js v22.11.0 文档
- Node.js v22.11.0
- 目录
-
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- module/typescript TS 模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- 其他版本
权限#
¥Permissions
权限可用于控制 Node.js 进程可以访问哪些系统资源,或者进程可以对这些资源执行哪些操作。
¥Permissions can be used to control what system resources the Node.js process has access to or what actions the process can take with those resources.
-
基于进程的权限 控制 Node.js 进程对资源的访问。可以完全允许或拒绝资源,或者可以控制与其相关的操作。例如,可以允许文件系统读取而拒绝写入。此功能无法防止恶意代码。根据 Node.js 安全政策,Node.js 信任要求它运行的任何代码。
¥Process-based permissions control the Node.js process's access to resources. The resource can be entirely allowed or denied, or actions related to it can be controlled. For example, file system reads can be allowed while denying writes. This feature does not protect against malicious code. According to the Node.js Security Policy, Node.js trusts any code it is asked to run.
权限模型实现了 "安全带" 方法,可防止受信任的代码无意中更改文件或使用未明确授予访问权限的资源。它在存在恶意代码的情况下不提供安全保障。恶意代码可以绕过权限模型并执行任意代码,而不受权限模型施加的限制。
¥The permission model implements a "seat belt" approach, which prevents trusted code from unintentionally changing files or using resources that access has not explicitly been granted to. It does not provide security guarantees in the presence of malicious code. Malicious code can bypass the permission model and execute arbitrary code without the restrictions imposed by the permission model.
如果你发现潜在的安全漏洞,请参阅我们的 安全政策。
¥If you find a potential security vulnerability, please refer to our Security Policy.
基于进程的权限#
¥Process-based permissions
权限模型#
¥Permission Model
¥Stability: 1.1 - Active development
Node.js 权限模型是一种在执行期间限制对特定资源的访问的机制。API 存在于标志 --experimental-permission
之后,启用后将限制对所有可用权限的访问。
¥The Node.js Permission Model is a mechanism for restricting access to specific
resources during execution.
The API exists behind a flag --experimental-permission
which when enabled,
will restrict access to all available permissions.
可用权限由 --experimental-permission
标志记录。
¥The available permissions are documented by the --experimental-permission
flag.
使用 --experimental-permission
启动 Node.js 时,通过 fs
模块访问文件系统、生成进程、使用 node:worker_threads
、使用原生插件、使用 WASI 和启用运行时检查器的能力将受到限制。
¥When starting Node.js with --experimental-permission
,
the ability to access the file system through the fs
module, spawn processes,
use node:worker_threads
, use native addons, use WASI, and enable the runtime inspector
will be restricted.
$ node --experimental-permission index.js
node:internal/modules/cjs/loader:171
const result = internalModuleStat(receiver, filename);
^
Error: Access to this API has been restricted
at stat (node:internal/modules/cjs/loader:171:18)
at Module._findPath (node:internal/modules/cjs/loader:627:16)
at resolveMainPath (node:internal/modules/run_main:19:25)
at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:76:24)
at node:internal/main/run_main_module:23:47 {
code: 'ERR_ACCESS_DENIED',
permission: 'FileSystemRead',
resource: '/home/user/index.js'
}
允许访问生成进程和创建工作线程可以分别使用 --allow-child-process
和 --allow-worker
来完成。
¥Allowing access to spawning a process and creating worker threads can be done
using the --allow-child-process
and --allow-worker
respectively.
要在使用权限模型时允许原生插件,请使用 --allow-addons
标志。对于 WASI,请使用 --allow-wasi
标志。
¥To allow native addons when using permission model, use the --allow-addons
flag. For WASI, use the --allow-wasi
flag.
运行时 API#
¥Runtime API
通过 --experimental-permission
标志启用权限模型时,新属性 permission
将添加到 process
对象。此属性包含一个功能:
¥When enabling the Permission Model through the --experimental-permission
flag a new property permission
is added to the process
object.
This property contains one function:
permission.has(scope[, reference])
#
在运行时检查权限的 API 调用 (permission.has()
)
¥API call to check permissions at runtime (permission.has()
)
process.permission.has('fs.write'); // true
process.permission.has('fs.write', '/home/rafaelgss/protected-folder'); // true
process.permission.has('fs.read'); // true
process.permission.has('fs.read', '/home/rafaelgss/protected-folder'); // false
文件系统权限#
¥File System Permissions
默认情况下,权限模型通过 node:fs
模块限制对文件系统的访问。它不能保证用户无法通过其他方式(例如通过 node:sqlite
模块)访问文件系统。
¥The Permission Model, by default, restricts access to the file system through the node:fs
module.
It does not guarantee that users will not be able to access the file system through other means,
such as through the node:sqlite
module.
要允许访问文件系统,请使用 --allow-fs-read
和 --allow-fs-write
标志:
¥To allow access to the file system, use the --allow-fs-read
and
--allow-fs-write
flags:
$ node --experimental-permission --allow-fs-read=* --allow-fs-write=* index.js
Hello world!
(node:19836) ExperimentalWarning: Permission is an experimental feature
(Use `node --trace-warnings ...` to show where the warning was created)
两个标志的有效参数是:
¥The valid arguments for both flags are:
-
*
- 分别允许所有FileSystemRead
或FileSystemWrite
操作。¥
*
- To allow allFileSystemRead
orFileSystemWrite
operations, respectively. -
以逗号 (
,
) 分隔的路径分别仅允许匹配FileSystemRead
或FileSystemWrite
操作。¥Paths delimited by comma (
,
) to allow only matchingFileSystemRead
orFileSystemWrite
operations, respectively.
示例:
¥Example:
-
--allow-fs-read=*
- 它将允许所有FileSystemRead
操作。¥
--allow-fs-read=*
- It will allow allFileSystemRead
operations. -
--allow-fs-write=*
- 它将允许所有FileSystemWrite
操作。¥
--allow-fs-write=*
- It will allow allFileSystemWrite
operations. -
--allow-fs-write=/tmp/
- 它将允许FileSystemWrite
访问/tmp/
文件夹。¥
--allow-fs-write=/tmp/
- It will allowFileSystemWrite
access to the/tmp/
folder. -
--allow-fs-read=/tmp/ --allow-fs-read=/home/.gitignore
- 它允许FileSystemRead
访问/tmp/
文件夹和/home/.gitignore
路径。¥
--allow-fs-read=/tmp/ --allow-fs-read=/home/.gitignore
- It allowsFileSystemRead
access to the/tmp/
folder and the/home/.gitignore
path.
也支持通配符:
¥Wildcards are supported too:
-
--allow-fs-read=/home/test*
将允许读取与通配符匹配的所有内容。例如:/home/test/file1
或/home/test2
¥
--allow-fs-read=/home/test*
will allow read access to everything that matches the wildcard. e.g:/home/test/file1
or/home/test2
传递通配符 (*
) 后,所有后续字符都将被忽略。例如:/home/*.js
的工作方式与 /home/*
类似。
¥After passing a wildcard character (*
) all subsequent characters will
be ignored. For example: /home/*.js
will work similar to /home/*
.
初始化权限模型时,如果指定的目录存在,它将自动添加通配符 (*)。例如,如果 /home/test/files
存在,它将被视为 /home/test/files/*
。但是,如果目录不存在,则不会添加通配符,并且访问将仅限于 /home/test/files
。如果要允许访问尚不存在的文件夹,请确保明确包含通配符:/my-path/folder-do-not-exist/*
。
¥When the permission model is initialized, it will automatically add a wildcard
(*) if the specified directory exists. For example, if /home/test/files
exists, it will be treated as /home/test/files/*
. However, if the directory
does not exist, the wildcard will not be added, and access will be limited to
/home/test/files
. If you want to allow access to a folder that does not exist
yet, make sure to explicitly include the wildcard:
/my-path/folder-do-not-exist/*
.
权限模型约束#
¥Permission Model constraints
在使用此系统之前,你需要了解一些限制条件:
¥There are constraints you need to know before using this system:
-
该模型不会继承到子节点进程或工作线程。
¥The model does not inherit to a child node process or a worker thread.
-
使用权限模型时,以下功能将受到限制:
¥When using the Permission Model the following features will be restricted:
-
原生模块
¥Native modules
-
子进程
¥Child process
-
工作线程
¥Worker Threads
-
检查器协议
¥Inspector protocol
-
文件系统访问
¥File system access
-
WASI
-
-
权限模型是在 Node.js 环境搭建完成后初始化的。但是,某些标志(例如
--env-file
或--openssl-config
)被设计为在环境初始化之前读取文件。因此,此类标志不受权限模型规则的约束。这同样适用于可以通过v8.setFlagsFromString
在运行时设置的 V8 标志。¥The Permission Model is initialized after the Node.js environment is set up. However, certain flags such as
--env-file
or--openssl-config
are designed to read files before environment initialization. As a result, such flags are not subject to the rules of the Permission Model. The same applies for V8 flags that can be set via runtime throughv8.setFlagsFromString
. -
当启用权限模型时,无法在运行时请求 OpenSSL 引擎,从而影响内置的 crypto、https 和 tls 模块。
¥OpenSSL engines cannot be requested at runtime when the Permission Model is enabled, affecting the built-in crypto, https, and tls modules.
-
通过
node:fs
模块使用现有文件描述符会绕过权限模型。¥Using existing file descriptors via the
node:fs
module bypasses the Permission Model.
限制和已知问题#
¥Limitations and Known Issues
-
符号链接甚至会被跟踪到已授予访问权限的路径集之外的位置。相对符号链接可以允许访问任意文件和目录。在启用权限模型的情况下启动应用时,必须确保已授予访问权限的路径不包含相对符号链接。
¥Symbolic links will be followed even to locations outside of the set of paths that access has been granted to. Relative symbolic links may allow access to arbitrary files and directories. When starting applications with the permission model enabled, you must ensure that no paths to which access has been granted contain relative symbolic links.