单服务器集群部署
本页介绍 DolphinDB 单服务器集群部署相关内容，包括文章信息、集群节点类型说明，以及教程章节概览与入口。
Source: https://dolphindb.cn/blogs/4
What this page covers
- 文章信息与教程概览（标题、作者、日期、章节目录）。
- 下载与安装路径限制说明。
- 授权许可更新方法与社区版/企业版限制差异。
- 集群初始配置（controller/agent/cluster 等配置文件）。
- 启动与关闭方式，以及 Web 管理器访问与登录。
- 节点启动失败原因与排查线索。
- server 版本升级步骤与验证方法。
技能认证特训营第二期报名提示
页面顶部包含活动提示与限时报名链接信息。
- 提示“技能认证特训营第二期”相关报名入口。
- 报名信息被描述为限时，并提及专属福利优惠。
单服务器集群部署（文章信息与教程概览）
本节给出文章标题、作者与日期信息，并介绍 DolphinDB 集群节点类型与教程章节目录。
- 文章给出发布日期与作者信息。
- 介绍集群包含数据节点、代理节点与控制节点三类节点。
- 教程覆盖部署步骤，并分析节点启动失败的可能原因。
- 提供章节目录链接，便于按主题跳转阅读。
下载
本节说明从官网下载安装包并解压到指定目录，同时提示安装路径的字符限制。
- 说明从 DolphinDB 官网下载并解压到指定目录。
- 安装路径目录名不能包含空格字符。
- 安装路径目录名不能包含中文字符。
- 若路径不满足限制，可能导致数据节点启动失败。
软件授权许可更新
本节说明企业版试用授权许可的更新方式、物理节点的许可文件更新要求，以及社区版与企业版的资源支持差异与限制。
- 企业版试用授权许可通过替换授权许可文件更新。
- 每个物理节点的授权许可文件都需要更新。
- 社区版 license 最多支持 2 个节点。
- 示例 license 文件路径为 /DolphinDB/server/dolphindb.lic。
DolphinDB 集群初始配置
本节描述集群启动前的必要配置，并给出 controller.cfg、cluster.nodes、cluster.cfg 与 agent.cfg 等配置要点与示例。
- 集群启动前必须配置控制节点与代理节点。
- 数据节点可在集群启动后通过网络界面配置或在初始阶段配置。
- controller.cfg 中仅 localSite 为必需参数，其它为可选参数。
- localSite 格式为 IP:端口:节点别名，且 IP 地址为内网 IP。
- cluster.nodes 文件用于存放代理节点与数据节点信息，并标注节点类型。
DolphinDB 集群启动与关闭（命令行与 Web 管理器）
本节给出 Linux/Windows 下启动与关闭 agent、controller 的方式，并说明如何通过浏览器访问集群管理器、登录与启动数据节点，以及常见启动问题的定位线索。
- 提供 Linux 后台启动 agent 的命令示例（含 -console 0）。
- -console 默认值为 1；后台运行需设置为 0。
- 提供 Windows 启动 agent 的命令示例。
- 提供 Linux 后台启动 controller 的命令示例（含 -clusterConfig 与 -nodesFile）。
- 前端交互模式关闭节点可在控制台输入 "quit"。
- 启动 controller 与 agent 后，可在浏览器访问控制节点地址（示例 192.168.1.103:8920）。
- 集群管理器目前支持 Chrome 与 Firefox。
- 默认系统管理员账号为 admin，默认密码为 123456。
节点启动失败可能原因分析
本节列举节点长时间无法启动的原因与排查线索，包括端口、防火墙、配置书写、节点文件内容与宏变量使用等。
- 端口号被占用可能导致节点启动失败。
- 防火墙未开放端口可能导致节点启动失败。
- 配置文件中 IP、端口号或节点别名书写不正确可能导致失败。
- cluster.nodes 第一行为空行可能导致加载失败并在 log 中提示输入文件为空。
- 在明确节点的情况下使用 cluster.cfg 宏变量 <ALIAS> 可能导致节点无法正常启动。
基于 Web 的集群管理
本节说明 Web 集群管理界面可用于修改控制节点参数、增删数据节点、修改数据节点参数，并给出变更生效的重启条件与相关注意事项。
- Web 集群管理界面提供更改集群配置的相关功能。
- 在 “Controller Config” 界面修改参数后需重启控制节点才生效。
- “Nodes Setup” 可添加或删除数据节点，并同步到 cluster.nodes。
- 删除已存放数据的节点可能造成数据丢失。
- “Nodes Config” 可设置数据节点运行参数，且重启所有数据节点后生效。
DolphinDB server 版本的更新
本节给出集群模式升级 server 的步骤，包括关闭节点、备份元数据、下载解压新版本、覆盖文件注意事项与升级验证。
- 升级前需正常关闭所有节点（含数据节点、控制节点和代理节点）。
- 升级步骤包含备份元数据文件。
- 提供下载更新版本安装包的命令示例（wget）。
- 说明覆盖升级时不覆盖 config、data、log 目录与 dolphindb.cfg。
- 升级后可通过 GUI 连接数据节点执行 version() 检查版本信息。
DolphinDB 集群详细配置与参数意义（帮助文档链接）
本节提供集群配置帮助文档的中文与英文链接入口。
- 提供中文集群配置帮助文档链接：http://www.dolphindb.cn/cn/help/Setup.html。
- 提供英文集群配置帮助文档链接：https://www.dolphindb.com/help/ClusterSetup.html。
Facts Index
| Entity | Attribute | Value | Confidence |
|---|---|---|---|
| 技能认证特训营第二期 | status | 正式开启（提供限时报名链接并称可享专属福利优惠） | medium |
| 单服务器集群部署 | publish_date | 2021-05-14 | high |
| 单服务器集群部署 | author | liang.lin | high |
| DolphinDB 集群 | node_types | 包含三种类型节点：数据节点（data node）、代理节点（agent）和控制节点（controller） | high |
| 数据节点（data node） | purpose | 用于数据存储、查询以及计算 | high |
| 代理节点（agent） | purpose | 用于关闭或开启数据节点 | high |
| 控制节点（controller） | purpose | 用于集群管理 | high |
| 本教程 | coverage | 讲述单服务器集群部署步骤，并分析节点启动失败的可能原因 | high |
| DolphinDB 安装路径目录名 | restriction | 不能含有空格字符，也不能含有中文字符，否则启动数据节点时会失败 | high |
| 企业版试用授权许可 | update_method | 替换授权许可文件；每个物理节点的授权许可文件都需要更新 | high |
| 企业版 vs 社区版 | capabilities | 企业版支持更多的节点、CPU 内核和内存 | medium |
| 社区版 license | max_nodes_supported | 最多支持 2 个节点 | high |
| 本教程示例集群 | node_count_requirement | 使用 4 节点，因此必须使用支持 4 个以上数据节点的企业版 license | high |
| license 文件路径 | path | /DolphinDB/server/dolphindb.lic | high |
| 集群启动前配置 | must_configure | 必须配置控制节点和代理节点；数据节点可在集群启动后通过网络界面配置或在初始阶段配置 | high |
| 集群配置与授权文件 | constraint | 配置时需核对授权文件规定的节点个数及每个节点最多内核；超出授权将导致集群无法正常启动，异常信息记录在 log 文件 | high |
| server 目录下子目录 | directories | 在 Linux 示例中创建 config、data、log 子目录；这些子目录用于方便理解但不是必须 | high |
| controller.cfg | required_parameter | 只有 localSite 参数是必需的，其它参数都是可选参数 | high |
| controller.cfg | example_parameters | localSite=192.168.1.103:8920:ctl8920 localExecutors=3 maxConnections=512 maxMemSize=16 webWorkerNum=4 workerNum=4 dfsReplicationFactor=1 dfsReplicaReliabilityLevel=0 dataSync=1 | high |
| localSite 参数 | format_and_requirement | 格式为 IP地址:端口号:节点别名；IP 地址为内网 IP；所有字段均为必选项 | high |
| localExecutors 参数 | default_rule | 默认值是 CPU 的内核数量 - 1 | high |
| webWorkerNum 参数 | default_value | 默认值是 1 | high |
| workerNum 参数（controller） | default_rule | 默认值是 CPU 的内核数量 | high |
| dfsReplicationFactor 参数 | default_value | 默认值是 2 | high |
| dfsReplicaReliabilityLevel 参数 | meaning_and_defaults | 0：多个副本可以保存在同一台物理服务器上；1：不可以；默认值是 0 | high |
| dataSync 参数 | dependency | 开启后数据库日志在事务提交前强制持久化到磁盘，cluster.cfg 中 chunkCacheEngineMemSize 也需要配置 | high |
| cluster.nodes 文件 | purpose | 用于存放集群代理节点和数据节点信息；配置分两列：第一列为 IP:端口:别名（冒号分隔），第二列说明节点类型（agent 或 datanode）；节点别名大小写敏感且在集群内必须唯一 | high |
| 本教程示例数据节点数量 | count | 4 个数据节点（可更改节点个数） | high |
| cluster.nodes 示例内容 | entries | 包含 agent 与 DFS_NODE1~DFS_NODE4：192.168.1.103:8910:agent,agent 以及 192.168.1.103:8921~8924:DFS_NODE1~DFS_NODE4,datanode（含表头 localSite,mode） | high |
| cluster.cfg | scope | 适用于集群中所有数据节点 | high |
| cluster.cfg 示例参数 | example_parameters | maxConnections=512 maxMemSize=32 workerNum=8 localExecutors=7 webWorkerNum=2 newValuePartitionPolicy=add chunkCacheEngineMemSize=1 | high |
| agent.cfg | required_parameters | 只有 LocalSite 和 controllerSite 是必需参数；其它参数均为可选参数 | high |
| agent.cfg 示例参数 | example_parameters | workerNum=3 localExecutors=2 maxMemSize=4 localSite=192.168.1.103:8910:agent controllerSite=192.168.1.103:8920:ctl8920 | high |
| controller.cfg 与 agent.cfg | consistency_requirement | controller.cfg 的 localSite 应与所有 agent.cfg 的 controllerSite 一致；若 controller.cfg 的 localSite 变化（即使只是 node alias 改变），所有 agent.cfg 的 controllerSite 都应相应改变 | high |
| Linux 后台启动 agent 命令 | command | nohup ./dolphindb -console 0 -mode agent -home data -config config/agent.cfg -logFile log/agent.log & | high |
| agent.log | location | 存放在 log 子目录下（可用于诊断 agent 启动问题） | high |
| 后台运行参数 -console | default_and_requirement | “-console”默认是 1；设置为后台运行必须设置为 0（-console 0），否则系统运行一段时间后会自动退出 | high |
| 启动参数说明 | parameter_meanings | -mode 表示节点性质；-home 指定数据以及元数据存储路径；-config 指定配置文件路径；-logFile 指定 log 文件路径 | high |
| Linux 前端交互启动 agent 命令 | command | ./dolphindb -mode agent -home data -config config/agent.cfg -logFile log/agent.log | high |
| Windows 启动 agent 命令 | command | dolphindb.exe -mode agent -home data -config config/agent.cfg -logFile log/agent.log | high |
| Linux 后台启动 controller 命令 | command | nohup ./dolphindb -console 0 -mode controller -home data -config config/controller.cfg -clusterConfig config/cluster.cfg -logFile log/controller.log -nodesFile config/cluster.nodes & | high |
| controller.log | location | 存放在 log 子目录下（用于诊断 controller 启动问题的提示文本中提及可查看该 log 文件） | medium |
| Linux 前端交互启动 controller 命令 | command | ./dolphindb -mode controller -home data -config config/controller.cfg -clusterConfig config/cluster.cfg -logFile log/controller.log -nodesFile config/cluster.nodes | high |
| Windows 启动 controller 命令 | command | dolphindb.exe -mode controller -home data -config config/controller.cfg -clusterConfig config/cluster.cfg -logFile log/controller.log -nodesFile config/cluster.nodes | high |
| 关闭节点（前端交互模式） | method | 在控制台输入 "quit" 退出 | high |
| 关闭节点（后台交互模式） | method | 使用 Linux kill 命令；示例通过 ps/grep/awk/xargs kill -TERM（示例用户名 ec2-user） | high |
| 集群管理器访问方式 | url_or_address | 启动控制节点和代理节点后，在浏览器地址栏输入 192.168.1.103:8920（8920 为控制节点端口号） | high |
| 集群管理器浏览器支持 | supported_browsers | 目前支持 Chrome 与 Firefox | high |
| DolphinDB database | access_control | 提供良好的权限控制机制；只有系统管理员才有权限做集群部署 | medium |
| 默认系统管理员账号 | credentials | 帐号名：admin；默认密码：123456 | high |
| admin 账号 | post_login_actions | 登录后可修改 "admin" 密码，也可添加用户或其他管理员账户 | medium |
| 启动数据节点耗时 | time_estimate | 可能耗时 30 秒到 1 分钟 | medium |
| 集群成功启动判定 | indicator | 若 State 栏全部为绿色对勾，则整个集群成功启动 | high |
| 节点日志文件位置（示例） | logfile_path_rule | 若节点名为 DFS_NODE1，对应 logFile 应在 log/DFS_NODE1.log | high |
| 节点启动错误 | error_message_example | log 可能出现 "Failed to bind the socket on XXXX"（XXXX 为待启动节点端口号） | high |
| 端口占用导致启动失败 | cause_and_mitigation | 可能因端口被其他程序占用；关闭其他程序后重新启动节点即可 | high |
| Linux 端口未释放导致启动失败 | cause_and_mitigation | 可能因刚关闭使用该端口的数据节点且 Linux kernel 尚未释放端口；等待约 30 秒后再启动节点 | high |
| startDataNode 函数 | purpose | 可在控制节点执行代码启动数据节点（示例启动 DFS_NODE1~DFS_NODE4） | high |
| 节点启动失败原因 | cause | 端口号被占用；可在 log 看到 "Failed to bind the socket on XXXX" | high |
| 节点启动失败原因 | cause | 防火墙未开放端口（需在防火墙中开放使用到的端口） | high |
| 节点启动失败原因 | cause | 配置文件中的 IP 地址、端口号或节点别名书写不正确 | high |
| 云端或 k8s 环境集群部署 | config_requirement | 需要在 agent.cfg 和 cluster.cfg 中加上配置项 lanCluster=0 | high |
| cluster.nodes 文件 | cause_of_failure | 第一行为空行可能导致失败；log 可能出现 "Failed to load the nodes file [XXXX/cluster.nodes] with error: The input file is empty."；删除空行后重启节点 | high |
| cluster.cfg 宏变量 <ALIAS> | cause_of_failure | 在明确节点的情况下使用 <ALIAS>（示例路径含 <ALIAS>）会导致节点无法正常启动；需删除 <ALIAS> 并替换为特定节点；若对所有节点使用则改为 persistenceDir = .../<ALIAS> | high |
| Web 集群管理界面 | capability | 提供更改集群配置的所有功能（用于实际使用中改变集群配置） | medium |
| 控制节点参数修改生效条件 | effective_after | 在“Controller Config”界面更改后需重启控制节点才能生效 | high |
| 更改控制节点 localSite 的影响 | dependency | 若改变控制节点的 localSite，一定要在所有 agent.cfg 中相应修改 controllerSite，否则集群无法正常运行 | high |
| Nodes Setup（Web） | capability | 可添加或删除数据节点；操作结果会同步至 cluster.nodes；新的配置在整个集群重启后生效 | high |
| 集群重启步骤（增删节点后） | procedure | （1）关闭所有数据节点，（2）关闭控制节点，（3）启动控制节点，（4）启动数据节点 | high |
| 删除节点操作 | risk | 如果节点上已经存放数据，删除节点可能会造成数据丢失 | high |
| 新增物理机器上的数据节点 | dependency | 需在新物理机器按 3.2 配置并启动新的代理节点，在 cluster.nodes 增添新的代理节点和数据节点信息，并重新启动控制节点 | high |
| Nodes Config（Web） | capability | 可对数据节点设置运行参数；支持修改 cluster.cfg 中已有参数并允许添加自定义配置；重启所有数据节点后生效 | high |
| DolphinDB server 版本更新 | step | 正常关闭所有节点（集群模式包括数据节点、控制节点和代理节点） | high |
| 元数据备份（集群模式默认路径示例） | paths_example | 以单机两数据节点（datanode1/datanode2）为例：/DolphinDBserver/data/DFSMetaLog.0/ 以及 /DolphinDBserver/data/datanode1/storage/CHUNK_METADATA/ 和 /DolphinDBserver/data/datanode2/storage/CHUNK_METADATA/ | medium |
| 元数据文件位置查找 | how_to_confirm | 若默认路径未找到，可通过配置文件参数 dfsMetaDir 与 chunkMetaDir 确认；若未指定但配置了 volumes，CHUNK_METADATA 目录在 volumes 指定目录下 | high |
| 下载更新版本安装包（示例） | command_example | wget https://www.dolphindb.cn/downloads/DolphinDB_Linux64_V1.30.6.zip（示例为 1.30.6 版本；不同版本文件名不同） | high |
| 解压更新包（示例） | command_example | unzip DolphinDB_Linux64_V1.30.6.zip -d v1.30.6 | high |
| 升级覆盖文件范围 | copy_rule | 拷贝新版本 server 子目录下除 config、data、log 目录和 dolphindb.cfg 外的所有文件和子目录到旧版本安装目录 server 下覆盖同名文件 | high |
| 升级注意事项 | do_not_override | 若旧版本 dolphindb.dos 初始化脚本中添加了脚本不要覆盖；旧版本 dolphindb.lic 若为企业版 license 也不要覆盖 | high |
| 升级验证 | verification_method | 重新启动所有节点后，GUI 连接任意数据节点执行 version() 查看版本信息以检查升级是否成功 | high |
| DolphinDB 集群配置帮助文档（中文） | link | http://www.dolphindb.cn/cn/help/Setup.html | high |
| DolphinDB 集群配置帮助文档（英文） | link | https://www.dolphindb.com/help/ClusterSetup.html | high |
| 单实例参数配置（用户手册链接） | link | https://www.dolphindb.cn/cn/help/StandaloneSetup.html | high |
| 教程章节目录（Gitee 链接） | links | 包含“1 下载、2 软件授权许可更新、3 DolphinDB集群初始配置、4 节点启动失败可能原因分析、5 基于Web的集群管理、6 DolphinDB server版本的更新、7 DolphinDB集群详细配置以及参数意义”的对应链接（位于 gitee.com/dolphindb/Tutorials_CN/...single_machine_cluster_deploy.md） | high |