跳转到内容
OpenClaw 不踩坑恶意 Skills ,企业需 Skills Registry:Nacos 3.2 发布点此了解

系统参数

本文整理 Nacos 3.2.x 常用服务端参数。主要来源是发行包中的 ${nacos.home}/conf/application.properties,并结合当前代码中的配置读取逻辑补充说明。

如果你正在部署生产集群,建议先阅读部署最佳实践,再回到本文确认具体参数。

配置放在哪里

Nacos Server 的主要配置文件是 ${nacos.home}/conf/application.properties。启动脚本会额外带上:

Terminal window
--spring.config.additional-location=file:${BASE_DIR}/conf/

同一个参数可以来自配置文件、JVM -D 参数或启动脚本。一般情况下,JVM 参数优先级高于配置文件。带 (-D) 标识的参数通常需要通过启动脚本或 JVM 参数设置。

基础启动参数

参数名说明默认值
nacos.home(-D)Nacos 根目录。安装目录
nacos.standalone(-D)是否以单机模式启动。startup.sh -m standalone 会设置该参数。false
nacos.functionMode(-D)启动功能模式。all 表示全部模块;也可通过启动脚本设置为 confignamingmicroserviceaiall
nacos.deployment.type(-D)部署形态。启动脚本默认设置为 merged;独立控制台部署时会使用控制台相关配置。merged
nacos.server.main.portNacos Server 主端口。8848
nacos.server.contextPathNacos Server HTTP 上下文路径。/nacos
spring.config.additional-location额外配置文件路径。多个路径用逗号分隔。${nacos.home}/conf/
server.error.include-messageSpring Boot 错误响应是否包含 message。ALWAYS
server.max-http-request-header-sizeHTTP 请求头大小上限,启动脚本默认设置。524288

网络与节点地址

参数名说明默认值
nacos.server.ip(-D)指定本机 IP。优先级高于自动探测和 nacos.inetutils.ip-address
nacos.inetutils.ip-address指定本机 IP,通常用于多网卡或容器网络。
nacos.inetutils.prefer-hostname-over-ip节点地址优先使用 hostname。开启后,cluster.conf 也应使用可解析的 hostname。false
nacos.remote.grpc.listen.ip(-D)gRPC 端口监听 IP。未设置时通常监听所有网卡。

数据库

Nacos 通过数据源方言插件支持 Derby、MySQL、PostgreSQL、Oracle 和自定义数据库类型。更多安装方式、社区插件和 Oracle 版本要求见多数据源插件

参数名说明默认值
spring.sql.init.platform数据库类型。可设置为 derbymysqlpostgresqloracle 或自定义方言插件类型。oracle 要求 Oracle 12c 及以上版本。
db.num数据库连接地址数量。0
db.url.0db.url.1JDBC URL。通过下标配置多个连接地址。
db.userdb.password所有连接共用的数据库账号密码。
db.user.0db.password.0指定下标连接的账号密码。需要每个连接不同账号时使用。
db.pool.config.*HikariCP 连接池参数,例如 db.pool.config.connectionTimeoutHikariCP 默认值
nacos.plugin.datasource.log.enabled是否输出数据源插件相关日志。true

Web 与控制台

Nacos 3.x 默认将 Server 和 Console 分成两个端口。Server API 默认是 8848,新控制台默认是 8080。控制台使用方式见控制台手册

参数名说明默认值
nacos.console.port控制台端口。8080
nacos.console.contextPath控制台上下文路径。
nacos.console.remote.server.context-path独立控制台访问远端 Nacos Server 时使用的 Server 上下文路径。/nacos
nacos.console.ui.enabled是否启用控制台 UI。true
nacos.console.ui.default默认控制台 UI。可选 nextlegacynext
spring.servlet.multipart.max-file-size控制台上传单文件大小上限,例如 Skill zip。10MB
spring.servlet.multipart.max-request-size控制台上传请求总大小上限。10MB
server.servlet.encoding.charsetServlet 编码。UTF-8

控制台 CORS

参数名说明默认值
nacos.console.cors.allow-credentials是否允许携带 Cookie、Authorization header、TLS client certificate 等凭据。true
nacos.console.cors.allowed-headers允许的请求头。留空表示允许所有请求头。
nacos.console.cors.max-ageCORS 预检请求缓存时间,单位秒。18000
nacos.console.cors.allowed-methods允许的 HTTP 方法。留空表示允许所有方法。
nacos.console.cors.allowed-origins允许的来源。留空表示允许所有来源模式。

访问日志与监控

监控指标暴露和告警建议见监控手册

参数名说明默认值
server.tomcat.accesslog.enabled是否开启访问日志。true
server.tomcat.accesslog.max-days访问日志保留天数。30
server.tomcat.accesslog.pattern访问日志格式。发行包默认格式
server.tomcat.basedirTomcat 工作目录和访问日志基准目录。file:.
management.endpoints.web.exposure.includeActuator 暴露的 endpoint。开启 Prometheus 指标时加入 prometheus
management.metrics.export.elastic.enabled是否启用 Elastic metrics exporter。false
management.metrics.export.influx.enabled是否启用 Influx metrics exporter。false
nacos.core.monitor.topn.enabled是否开启 TopN 监控统计。true
nacos.core.monitor.topn.countTopN 统计数量。10
nacos.core.monitor.topn.internalMsTopN 统计周期,单位毫秒。60000

集群成员发现

参数名说明默认值
nacos.member.list(-D)集群成员列表。启动脚本 -c 参数会写入该 JVM 参数;当 cluster.conf 不存在时可使用。
nacos.member-change-event.queue.size集群成员变更事件队列大小。128
nacos.core.member.lookup.type成员发现方式。可选 fileaddress-serverfile
nacos.core.address-server.retry地址服务器初始化重试次数。5
address.server.domain地址服务器域名。jmenv.tbsite.net
address.server.port地址服务器端口。8080
address.server.url地址服务器请求路径。/nacos/serverlist
nacos.core.member.meta.site节点站点元数据。
nacos.core.member.meta.adweight节点权重元数据。
nacos.core.member.meta.weight节点权重元数据。

gRPC

参数名说明默认值
nacos.remote.server.grpc.sdk.max-inbound-message-sizeSDK gRPC 请求最大接收大小,单位 byte。10485760
nacos.remote.server.grpc.sdk.keep-alive-timeSDK gRPC keepalive 间隔,单位毫秒。7200000
nacos.remote.server.grpc.sdk.keep-alive-timeoutSDK gRPC keepalive 超时,单位毫秒。20000
nacos.remote.server.grpc.sdk.permit-keep-alive-time允许客户端配置的最小 keepalive 间隔,单位毫秒。300000
nacos.remote.server.grpc.cluster.max-inbound-message-size集群间 gRPC 请求最大接收大小,单位 byte。10485760
nacos.remote.server.grpc.cluster.keep-alive-time集群间 gRPC keepalive 间隔,单位毫秒。7200000
nacos.remote.server.grpc.cluster.keep-alive-timeout集群间 gRPC keepalive 超时,单位毫秒。20000
nacos.remote.server.grpc.cluster.permit-keep-alive-time集群间 gRPC 允许的最小 keepalive 间隔,单位毫秒。300000
remote.executor.times.of.processors(-D)服务端请求处理线程数相对 CPU 核数的倍数。16
remote.executor.queue.size(-D)服务端请求处理线程池队列大小。16384

Distro 与 Raft

Distro 和 Raft 是 Nacos 内部一致性协议参数。除非已经定位到协议层瓶颈或由维护者建议,生产环境不建议随意调整。

Distro

参数名说明默认值
nacos.core.protocol.distro.data.sync.delayMs数据同步延迟,单位毫秒。相同数据在延迟窗口内会合并同步。1000
nacos.core.protocol.distro.data.sync.timeoutMs单次数据同步超时,单位毫秒。3000
nacos.core.protocol.distro.data.sync.retryDelayMs同步失败后的重试延迟,单位毫秒。3000
nacos.core.protocol.distro.data.verify.intervalMs已同步数据校验间隔,单位毫秒。5000
nacos.core.protocol.distro.data.verify.timeoutMs单次数据校验超时,单位毫秒。3000
nacos.core.protocol.distro.data.load.retryDelayMs启动加载快照失败后的重试延迟,单位毫秒。30000

Raft

Raft 参数通过 nacos.core.protocol.raft.data.* 配置。data 是当前代码中 RaftConfig 的配置映射字段,不应省略。

参数名说明默认值
nacos.core.protocol.raft.data.election_timeout_ms选举超时时间,单位毫秒。5000
nacos.core.protocol.raft.data.snapshot_interval_secs快照执行周期,单位秒。1800
nacos.core.protocol.raft.data.core_thread_numRaft 内部工作线程数。8
nacos.core.protocol.raft.data.cli_service_thread_numRaft 业务请求处理线程数。4
nacos.core.protocol.raft.data.read_index_type线性读策略。ReadOnlySafe
nacos.core.protocol.raft.data.rpc_request_timeout_msRaft RPC 请求超时,单位毫秒。5000
nacos.core.protocol.raft.data.max_byte_count_per_rpc单次 snapshot copy RPC 最大字节数。131072
nacos.core.protocol.raft.data.max_entries_sizeLeader 向 Follower 单次发送的最大日志条数。1024
nacos.core.protocol.raft.data.max_body_size发送日志的最大 body 大小。524288
nacos.core.protocol.raft.data.max_append_buffer_size日志写入缓冲区大小。262144
nacos.core.protocol.raft.data.max_election_delay_ms选举随机延迟最大值,单位毫秒。1000
nacos.core.protocol.raft.strict-modeRaft 启动校验严格模式。开启后,Raft 无法选举时 readiness 会返回失败。false

配置中心

配置中心的日常使用见配置中心手册

参数名说明默认值
nacos.config.push.maxRetryTime配置变更推送最大重试次数。50
nacos.config.retention.days配置历史保留天数。30
nacos.config.search.max_capacity内容搜索任务队列容量上限。4
nacos.config.search.max_thread内容搜索线程数上限。2
nacos.config.search.wait_timeout内容搜索等待超时,单位毫秒。8000
nacos.config.derby.ops.enabled使用 Derby 时是否开启 Derby 运维接口。false
nacos.persistence.sql.derby.limit.enabled使用 Derby 时是否限制可执行 SQL 范围。true
nacos.config.cache.type配置缓存实现类型。nacos
nacos.config.history.clear.name配置历史清理实现名称。nacos

服务发现

服务发现的日常使用见注册中心手册

参数名说明默认值
nacos.naming.data.warmup是否在启动时等待服务发现数据预热。开启后 readiness 可能在预热完成前失败。false
nacos.naming.expireInstance是否自动摘除过期临时实例。true
nacos.naming.empty-service.auto-clean是否自动清理空服务。true
nacos.naming.empty-service.clean.initial-delay-ms空服务清理首次延迟,单位毫秒。50000
nacos.naming.empty-service.clean.period-time-ms空服务清理周期,单位毫秒。30000
nacos.naming.clean.empty-service.interval空服务清理间隔,单位毫秒。60000
nacos.naming.clean.empty-service.expired-time空服务过期时间,单位毫秒。60000
nacos.naming.clean.expired-metadata.interval过期元数据清理间隔,单位毫秒。5000
nacos.naming.clean.expired-metadata.expired-time过期元数据保留时间,单位毫秒。60000
nacos.naming.client.expired.time临时 Client 数据过期时间,单位毫秒。180000
nacos.naming.push.pushTaskDelay服务推送延迟,单位毫秒。500
nacos.naming.push.pushTaskTimeout服务推送执行超时,单位毫秒。5000
nacos.naming.push.pushTaskRetryDelay服务推送失败重试延迟,单位毫秒。1000
nacos.naming.service.metadata.length服务元数据总长度限制。1024

参数校验

参数名说明默认值
nacos.core.param.check.enabled是否开启服务端参数校验。规则见参数校验true
nacos.core.param.check.checker参数校验器名称。默认使用内置校验器。default

鉴权与可见性

鉴权配置应优先阅读权限校验OIDC/OAuth2 认证。可见性插件见可见性插件

参数名说明默认值
nacos.core.auth.system.type鉴权插件类型。默认实现为 nacos;也可接入 LDAP、OIDC/OAuth2 或自定义插件。nacos
nacos.core.auth.enabled是否开启 SDK/gRPC 请求鉴权。false
nacos.core.auth.admin.enabled是否开启 /v3/admin/* Admin API 鉴权。true
nacos.core.auth.console.enabled是否开启 /v3/console/* Console API 和登录鉴权。true
nacos.core.auth.caching.enabled是否缓存鉴权信息。开启后权限变更会有短暂延迟。true
nacos.core.auth.server.identity.keyServer 间请求身份标识 key。开启鉴权时必须设置。
nacos.core.auth.server.identity.valueServer 间请求身份标识 value。开启鉴权时必须设置。
nacos.security.ignore.urls鉴权忽略路径。该参数属于历史兼容项,未来可能废弃。发行包默认值
nacos.core.auth.plugin.nacos.token.cache.enable默认鉴权插件是否缓存 token。false
nacos.core.auth.plugin.nacos.token.expire.seconds默认鉴权插件 token 过期时间,单位秒。18000
nacos.core.auth.plugin.nacos.token.secret.key默认鉴权插件 JWT 签名密钥。需要使用 Base64 字符串,原始密钥长度不少于 32 字符。
nacos.core.auth.nacos.anonymous.ai.enabled是否允许 AI 资源匿名读取。当前主要面向 Skill 和 AgentSpec。false
nacos.plugin.visibility.enabled是否开启可见性插件。true
nacos.plugin.visibility.type可见性插件类型。默认 nacos 实现会复用默认鉴权插件用户信息。nacos

LDAP、OIDC 与 OAuth2

LDAP 从 Nacos 3.2 起作为可选插件独立维护。OIDC/OAuth2 也是插件能力。使用前请确认对应插件已经随发行包提供或已放入插件目录。

参数名说明默认值
nacos.core.auth.ldap.urlLDAP server 地址。
nacos.core.auth.ldap.basedcLDAP base DN。
nacos.core.auth.ldap.userDnLDAP 管理用户 DN。
nacos.core.auth.ldap.passwordLDAP 管理用户密码。
nacos.core.auth.ldap.userdn登录用户 DN 模板,{0} 表示用户名。
nacos.core.auth.ldap.filter.prefix用户过滤字段前缀。uid
nacos.core.auth.ldap.case.sensitive用户名是否大小写敏感。true
nacos.core.auth.ldap.ignore.partial.result.exception是否忽略 LDAP partial result 异常。false
nacos.core.auth.plugin.oidc.issuer-uriOIDC issuer URI,用于自动发现。
nacos.core.auth.plugin.oidc.client-idOIDC client id。
nacos.core.auth.plugin.oidc.client-secretOIDC client secret。
nacos.core.auth.plugin.oidc.scopeOIDC scope。openid
nacos.core.auth.plugin.oidc.token-validation-methodtoken 校验方式,可选 jwtintrospection
nacos.core.auth.plugin.oidc.jwks-cache-ttl-secondsJWKS 缓存时间,单位秒。
nacos.core.auth.plugin.oidc.username-claim用户名 claim。sub
nacos.core.auth.plugin.oidc.roles-claim角色 claim。
nacos.core.auth.plugin.oidc.admin-role管理员角色名。
nacos.core.auth.plugin.oidc.auto-create-user首次登录时是否自动创建用户。true
nacos.core.auth.plugin.oidc.authorization-endpoint外部授权端点。
nacos.core.auth.plugin.authorization-timeout-ms外部授权请求超时,单位毫秒。
nacos.core.auth.plugin.oidc.strict-nonce-validation是否严格校验 nonce。false
nacos.core.auth.plugin.oidc.strict-audience-validation是否严格校验 audience。false

插件参数

插件体系说明见插件化概览

参数名说明默认值
nacos.custom.environment.enabled是否启用自定义环境变量插件。false
nacos.plugin.control.manager.type流量防护插件类型。配置为 nacos 时使用默认实现。
nacos.plugin.control.rule.local.basedir本地流量防护规则目录。${nacos.home}
nacos.plugin.control.rule.external.storage外部规则存储类型,需要自行实现。
nacos.core.config.plugin.webhook.enabled是否启用配置变更 Webhook 插件。false
nacos.core.config.plugin.webhook.urlWebhook 地址。
nacos.core.config.plugin.webhook.contentMaxCapacityWebhook 推送内容最大大小,单位 byte。102400
nacos.core.config.plugin.whitelist.enabled是否启用配置导入后缀白名单插件。false
nacos.core.config.plugin.whitelist.suffixs允许导入的配置文件后缀。xml,text,properties,yaml,html
nacos.core.config.plugin.fileformatcheck.enabled是否启用导入文件格式检查插件。false

Istio 与 Prometheus 服务发现

这两类能力属于长期存在的生态融合能力,使用方式见生态融合概览

参数名说明默认值
nacos.extension.naming.istio.enabled是否加载 Istio 模块。false
nacos.istio.mcp.server.enabled是否开启 Istio MCP server。false
nacos.istio.mcp.server.portIstio MCP server 端口。18848
nacos.istio.server.full是否使用全量推送。true
nacos.istio.debounce.maxIstio 推送防抖最大等待时间,单位毫秒。5000
nacos.istio.debounce.afterIstio 推送防抖等待时间,单位毫秒。100
nacos.istio.domain.suffixIstio 域名后缀。nacos
nacos.prometheus.metrics.enabled是否开启 Prometheus 服务发现辅助接口。false

AI 管理中心

AI 管理中心的使用方式见AI 管理中心概述。下面参数只负责模块开关、协议适配、导入和发布 Pipeline。

参数名说明默认值
nacos.extension.ai.enabled是否启用 AI 模块。AI 模块需要配置中心和服务发现模块同时启用。true
nacos.ai.mcp.registry.enabled是否启用官方 MCP Registry 协议适配。开启后会使用 nacos.ai.registry.port 暴露独立端口。false
nacos.ai.skill.registry.enabled是否启用 Skill Registry 协议适配。开启后会使用 nacos.ai.registry.port 暴露独立端口。false
nacos.ai.registry.portAI Registry 协议适配端口。9080
nacos.ai.mcp.registry.port旧参数名,已废弃。请改用 nacos.ai.registry.port9080
nacos.plugin.ai-pipeline.enabled是否启用 AI 发布 Pipeline。未配置时不会主动禁用,但如果 type 为空,Pipeline 不会执行。
nacos.plugin.ai-pipeline.typePipeline 节点类型,例如 skill-scanner。多个类型用逗号分隔。
nacos.plugin.ai-pipeline.skill-scanner.enabled传给内置 skill-scanner 节点的启用配置。
nacos.plugin.ai-pipeline.skill-scanner.command外部 Skill 扫描工具命令路径。
nacos.ai.skill.auto-publish-after-review.enabledSkill 审核通过后是否自动发布版本。false
nacos.ai.resource.import.enabled是否启用显式配置的 AI 资源导入来源。false
nacos.ai.resource.import.legacy-mcp-api-enabled是否临时重新开启已废弃的 MCP 导入 API。false
nacos.ai.resource.import.allow-user-url重新开启旧 MCP 导入 API 时,是否允许抓取用户提供的 URL。false
nacos.plugin.ai.importer.mcp.official.enabled是否启用内置官方 MCP Registry 导入来源。true
nacos.plugin.ai.importer.skills.well-known.enabled是否启用 Skill well-known 导入来源。false
nacos.plugin.ai.importer.skills.well-known.urlSkill well-known registry 根地址。
nacos.plugin.ai.importer.skills.skills-sh.enabled是否启用 skills.sh 导入来源。true
nacos.plugin.ai.importer.<preset>.allow-http是否允许指定来源使用非 HTTPS endpoint。仅受控环境中开启。false
nacos.plugin.ai.importer.<preset>.allow-private-network是否允许指定来源访问私网或 localhost endpoint。仅受控环境中开启。false

实验性功能

实验性功能不承诺长期稳定行为。使用前请阅读实验性功能概览

参数名说明默认值
nacos.k8s.sync.enabled是否开启内置 K8s sync 实验能力。false
nacos.k8s.sync.outsideCluster是否从 Kubernetes 集群外访问 API Server。false
nacos.k8s.sync.kubeConfig集群外访问时使用的 kubeconfig 路径。/.kube/config

兼容与迁移参数

这些参数用于升级、迁移或兼容旧行为。它们不代表新系统推荐模型。更多背景见兼容与废弃

参数名说明默认值
nacos.core.api.compatibility.client.enabled是否开启客户端 API 兼容能力。true
nacos.core.api.compatibility.admin.enabled是否开启 Admin API 兼容能力。false
nacos.core.api.compatibility.console.enabled是否开启 Console API 兼容能力。false
nacos.config.gray.compatible.model是否开启 Beta/Tag 灰度配置向新版灰度模型的兼容与迁移。true
nacos.gray.migrate.executor.multi灰度配置迁移线程数。8
nacos.config.namespace.compatible.mode是否开启空命名空间到 public 命名空间的兼容迁移。true
nacos.namespace.migrate.retry.times命名空间迁移失败重试次数。3
nacos.namespace.migrate.batch.size命名空间迁移批大小。100

启动脚本和镜像变量

发行包 startup.sh 支持以下常用启动参数:

启动参数说明对应配置
-m standalone单机模式启动。nacos.standalone=true
-m cluster集群模式启动。nacos.standalone=false
-f config只启动配置中心相关模块。nacos.functionMode=config
-f naming只启动服务发现相关模块。nacos.functionMode=naming
-f microservice启动微服务相关模块。nacos.functionMode=microservice
-f ai启动 AI 相关模块。nacos.functionMode=ai
-c设置集群成员列表。nacos.member.list
-p embedded集群模式下使用嵌入式存储。embeddedStorage=true
-d设置部署形态。nacos.deployment.type

使用官方容器镜像时,常见环境变量包括 MODENACOS_SERVERSPREFER_HOST_MODENACOS_AUTH_ENABLENACOS_AUTH_ADMIN_ENABLENACOS_AUTH_CONSOLE_ENABLENACOS_AUTH_TOKENNACOS_AUTH_IDENTITY_KEYNACOS_AUTH_IDENTITY_VALUENACOS_CONSOLE_PORT 等。不同镜像版本的转换脚本可能不同,生产部署建议挂载完整 application.properties,并以镜像仓库或 Helm Chart 的说明为准。