GanttProject Colloboque 实时协作服务器：从构建、运行到同步协议解析-北京尧图网络

桌面应用企业应用【免费下载链接】ganttprojectOfficial GanttProject repository.项目地址https://gitcode.com/gh_mirrors/ga/ganttproject点击查看免费下载导读本文围绕 GanttProject 仓库中的 cloud.ganttproject.colloboque/README.md 展开系统讲解 Colloboque——GanttProject 官方实时协作服务器的完整落地流程如何本地构建其依赖库、通过 Docker 初始化 PostgreSQL 数据库、以命令行参数启动开发服务器以及如何让两个 GanttProject 桌面客户端通过 WebSocket 实时同步任务数据。读完本文你将掌握 Colloboque 的构建运行环境、HTTP/WebSocket 通信协议、基于事务日志xlog与列族column families的冲突合并原理并了解当前版本所支持的能力边界。一、Colloboque 是什么GanttProject 的实时协作服务器Colloboque 是一个为 GanttProject 文档提供实时协作能力的独立服务端模块位于仓库的 cloud.ganttproject.colloboque 目录。它由 Kotlin 编写核心代码集中在 src/main/kotlin/cloud/ganttproject/colloboque 下包括ColloboqueServer.kt服务端核心负责接收客户端事务日志、校验基线事务 ID、应用更新并重新生成项目 XMLDevServer.kt开发服务器入口解析命令行参数并同时启动 HTTP 与 WebSocket 两个服务Postgres.kt/PostgreStorageApi.ktPostgreSQL 连接池与存储层实现PostgreXlogMerger.kt并发更新合并检测器ProjectFileUpdater.kt把 xlog 更新应用到项目 XML 的工具函数。其设计目标在 DesignDoc.md 中阐述得很清楚为关系型结构化数据提供实时协作协议并支持离线分支的自动化/辅助合并。文中给出了一个典型场景——任务表Task(id, start, duration, color)初始值为(1, 2023-09-01, 1d, red)在线客户端把颜色改成yellow同时离线客户端把开始日期改为2023-10-01并新增id2的任务合并后应得到(1, 2023-10-01, 1d, yellow)与(2, 2023-09-01, 1d, red)。即使两个用户同时在中心化数据库上修改同一行这也是一个不平凡的问题更何况用户可能长时间离线——Colloboque 要提供一套可靠的协议让离线用户能收到服务器更新或把离线期间产生的修改安全合并回去。DesignDoc 同时列出了一些备选技术路线逻辑复制、RAFT、PostgreSQL Multimaster、数据库分支与版本控制、CRDT、文本合并说明团队在方案选型上的权衡Colloboque 最终采用的是事务日志列族可串行化冲突检测的路线。二、构建服务器先构建共享库再构建 Colloboque2.1 从源码构建 GanttProject 库Colloboque 与 GanttProject 主工程紧密耦合共享大量代码如 XML 解析、任务管理器、存储层。因此 README 建议先在本地 Maven 仓库构建这些库便于修改库代码后立即在 Colloboque 中使用cd .. gradle publishtomavenlocal注意该命令应在仓库根目录ganttproject主工程所在目录执行构建产物会发布到本地 Maven 仓库。库的版本号由构建日期按YY.MM.DD模式生成例如 2024 年 1 月 4 日构建的库版本为24.01.04。2.2 构建 Colloboque 与 GitHub Packages 鉴权Colloboque 自身使用标准 Gradle 命令构建gradle build由于它依赖 GanttProject 的若干库这些库发布在 GitHub Packages 上构建时通常需要向 Gradle 传递 GitHub 用户名与 Personal Access TokenPAT通过两个项目属性project properties注入gradle -Pgpr.userGH_USERNAME -Pgpr.keyGH_PAT build也可以把gpr.user和gpr.key保存到本地的gradle.properties文件中注意不要提交到版本控制。README 中后续所有 Gradle 命令都假定访问所需库/仓库的凭据已配置完毕。关于 PAT 的申请细节README 提示参考 GitHub Packages 官方文档。如果已经按 2.1 节在本地构建并发布了库则可以不再依赖 GitHub Packages 的网络访问。此外gradle.properties 中声明了 Colloboque 的关键依赖版本kotlinVersion2.3.21、jooqVersion3.20.1。从 settings.gradle.kts 可以看到工程名为GanttProject Colloboque且通过 jOOQ 3.20 操作 PostgreSQLColloboqueServer.kt 中SQLDialect.POSTGRES即为佐证。三、环境准备初始化 PostgreSQL 数据库Colloboque 要求一个已初始化的 PostgreSQL 数据库。README 给出的最快捷方式是用 Docker 起一个本地实例docker run -d -p 5432:5432 --name dev-postgres -e POSTGRES_HOST_AUTH_METHODtrust postgres该命令会在 5432 端口启动 Postgres超级用户为postgres、密码为空trust认证。随后进入资源目录并执行初始化脚本cd src/main/resources/ psql -h localhost -U postgres -f ./init-colloboque-server.sql这里的src/main/resources/对应仓库中的 cloud.ganttproject.colloboque/src/main/resources 目录。初始化实际上由一组 SQL 脚本协作完成脚本作用init-colloboque-server.sql总入口依次执行 master 与 template 脚本并创建dev_all_projects数据库模板为project_database_templateinit-colloboque-master-database.sql创建colloboque数据库当前暂时为空init-colloboque-template-database.sql创建project_database_template模板库IS_TEMPLATEtrue定义clone_schema函数、Task可更新视图及其触发器database-schema-template.sql模板库内的表结构TaskName、TaskDates、TaskIntProperties、TaskTextProperties、TaskCostProperties、TaskClassProperties、Task视图、ProjectFileSnapshot、TransactionLog模板库的设计值得展开每个项目在 PostgreSQL 中对应一个独立 schema由PostgresConnectionFactory.getSchema()用projectRefid的 MurmurHash3 128 位哈希生成project_hash名称见 Postgres.kt。新项目初始化时PostgreStorageApi.initProject()调用clone_schema(project_template, schema, false)把模板 schema 连同结构克隆到新项目 schemaPostgreStorageApi.kt。clone_schema是一个 PL/pgSQL 函数会克隆序列、表、外键、视图、函数与触发器并在克隆后的默认值/约束里把source_schema引用替换为dest_schema除taskintpropertyname、tasktextpropertyname两个类型名保持指向源 schema。模板 schema 的核心是Task可更新视图它把任务的全部属性横向汇总为一行database-schema-template.sql第 58-83 行而INSTEAD OF触发器update_task_row()负责在INSERT/UPDATE时把属性按列族拆分写入不同的物理表init-colloboque-template-database.sql 第 249 行起任务名/编号 →TaskName驱动表任何任务都必然存在记录开始日期、工期、最早开始日期 →TaskDates必须原子更新所以放在同一张表成本计算标志与手工成本 →TaskCostProperties原子更新里程碑/项目任务标志 →TaskClassProperties原子更新其余字段completion、priority、color、shape、web_link、notes→TaskIntProperties/TaskTextProperties的键值行可相互独立更新。这个列族划分正是冲突合并能够成功的关键把相互独立的字段拆到不同物理行并发事务各自更新不同行时不会互相阻塞冲突概率被显著降低。SQL 注释也明确写道任务日期必须原子更新因此存储在同一张表、其他任务属性可以独立变更因此以行存储一行对应一个属性值实例。事务日志存储方面模板库定义了两张表ProjectFileSnapshot(base_txn_id BIGINT PRIMARY KEY, project_xml TEXT)每次提交后生成的项目 XML 快照TransactionLog(base_txn_id, log_record_num, log_record_json, PRIMARY KEY(base_txn_id, log_record_num))记录从客户端收到的日志其注释说明了设计动机——日志基于某个base_txn_id标识的数据库状态构建正常情况下每个 base 状态只有 1 条日志但客户端离线时多条日志会堆叠且都引用同一个 base txn ID直到服务器收到并应用它们database-schema-template.sql 第 90-100 行。四、运行开发服务器命令行参数与启动验证4.1 查看全部命令行参数Colloboque 的入口是 DevServer.kt 中的DevServerMain基于 Clikt 命令行框架实现。运行gradle run --args--help即可列出所有可用参数。结合源码开发服务器支持的参数及默认值如下参数含义默认值--portHTTP 服务监听端口9000--ws-portWebSocket 服务监听端口9001--pg-hostPostgreSQL 主机名localhost--pg-portPostgreSQL 端口5432--pg-super-userPostgreSQL 超级用户名postgres--pg-super-authPostgreSQL 超级用户密码空字符串源码中这些选项均通过option(...).int().default(...)声明DevServer.kt第 48-53 行帮助信息使用MordantHelpFormatter并显示默认值showDefaultValues true。注意开发服务器以超级用户身份连接 PostgreSQLPostgresConnectionFactory中username pgSuperUser源码中的TODO: replace the user注释表明这只是开发阶段的临时做法。4.2 启动服务器默认参数对本地开发已经足够直接运行gradle run启动成功后控制台会输出类似日志 Task :run 14:49:38.771 DEBUG [Startup main] - Starting dev Colloboque server on port 9000 14:49:38.883 DEBUG [Startup main] - Connected to the database. PostgreSQL 15.3 (Debian 15.3-1.pgdg1201) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit第一条日志来自DevServerMain.run()中的STARTUP_LOG.debug(Starting dev Colloboque server on port {}, port)第二条来自 Postgres.kt 连接池初始化时执行的SELECT version()。日志框架由 src/main/resources/logback.xml 配置。4.3 服务器内部结构HTTP 与 WebSocket 双通道DevServerMain.run()启动了两套服务DevServer.kt 第 62-74 行底层使用 NanoHTTPD / NanoWSDHTTP 服务ColloboqueHttpServer端口 9000提供三个端点GET /init?projectRefidid用空项目模板初始化指定项目实际调用ColloboqueServer.init()成功返回Ok缺少参数返回 400GET /返回HelloGET /p/read?projectRefidid读取项目当前 XML 快照返回 Base64 编码的 XML并附带ETag: -1、DigestXML 的 CRC32 校验和与BaseTxnId三个响应头。BaseTxnId头对客户端同步起点至关重要。WebSocket 服务ColloboqueWebSocketServer端口 9001是实时同步的主通道协议消息为纯文本帧客户端发送LISTEN projectRefid订阅某项目的更新广播服务端把连接加入connectedClients映射客户端发送XLOG base64提交事务日志——Base64 解码后是 JSON 序列化的InputXlogparseInputXlog中message.startsWith(XLOG )判定服务端把ServerResponseCommitResponse或ErrorResponse通过 JSON 广播给订阅了该项目且仍处于连接状态的客户端。通道方面服务端用 kotlinx.coroutines 的Channel串联请求与响应updateInputChannel、serverResponseChannel并用单线程 dispatcher 保证消息顺序wsCommunicationScope。五、客户端开发与实时同步工作流5.1 启动客户端GanttProject 主工程的构建运行说明见仓库根目录 README.mdgradle run可运行核心部分。README 指出为 Colloboque 开发调试直接gradle run即可——客户端启动后会尝试连接localhost:9000上的 Colloboque 服务器并打开一个只含单个任务的测试文档。5.2 客户端的同步开关与事件循环客户端侧的实时同步逻辑在 ColloboqueClient.kt。它通过系统属性或环境变量开关启用fun isColloboqueOn() System.getProperty(enable_colloboque, System.getenv(ENABLE_COLLOBOQUE) ?: false)即设置 JVM 属性-Denable_colloboquetrue或环境变量ENABLE_COLLOBOQUEtrue即可开启。启用后ColloboqueClient监听GPUndoManager的撤销事件undoableEditHappened一旦发生编辑就把projectDatabase.outgoingTransactions中的 xlog 事务发往服务器。客户端内部运行一个单线程事件循环runEventLoop用select在两条通道间仲裁内部通道收到本实例产生的更新时通过 WebSocket 发送InputXlog包含baseTxnId、userId、projectRefid、事务列表与clientTrackingCode并暂停继续接收内部更新直到收到服务器响应外部通道收到服务器广播的CommitResponse时先比较clientTrackingCode若响应不是自己发起的response.clientTrackingCode ! myBaseTxnCommitInfo.trackingCode则把response.logRecords应用到本地数据库即使是自己的更新也要用空事务推进本地baseTxnId。随后恢复接受内部更新。TxnCommitInfo类负责维护客户端基线事务 ID并在每次响应后校验oldTxnId是否与期望一致不一致则抛出IllegalStateException——这是客户端侧对服务器状态与本地预期不符的防御。当服务器广播的更新到达时客户端通过projectDatabase.addExternalUpdatesListener把数据库中的任务重新导入任务管理器installColloboque中importBufferProject的方式从而实现收到即应用、立即呈现。5.3 期望的行为与当前支持范围README 明确描述了预期效果两个 GanttProject 实例各自把更新发送到服务器同时接收服务器转发的更新并立即应用。当前版本支持的服务端更新类型为添加新任务adding a new task。这是 README 中明示的能力边界——文章不对此做额外夸大。从测试 ProjectFileUpdaterTest.kt 可以看到xlog 操作实际上覆盖了更细的 DTO 种类InsertOperationDto、UpdateOperationDto、DeleteOperationDto、MergeOperationDtoSqlStatementsGeneratorTest.kt 逐一验证了它们生成的 SQL但服务器层面当前只承诺添加新任务其余能力应视为演进中。六、服务端提交协议baseTxnId 校验与快照重建6.1 一次提交的完整链路ColloboqueServer.kt 的processUpdatesLoop()是服务端处理核心按顺序执行从updateInputChannel取出InputXlog读取项目当前快照actualSnapshot校验inputXlog.baseTxnId与快照的baseTxnId是否一致不一致则抛ColloboqueServerException(Base txn ID mismatch. Expected: ... Received: ...)调用storageApi.insertXlogs()持久化收到的日志记录调用applyXlog()逐条执行事务内的colloboqueOperations——每条操作经generateSqlStatement()转为 SQL如 INSERT/UPDATE/DELETE/MERGE并在同一个 PostgreSQL 事务中执行成功后generateNextTxnId()返回oldTxnId 1作为新基线调用buildProjectXml()基于新基线重新生成项目 XML从TransactionLog读取该基线之后的全部日志用updateProjectXml()逐条折叠到快照 XML 上保存新快照insertActualSnapshot(projectRefid, newBaseTxnId, projectXml)向serverResponseChannel发送CommitResponse(baseTxnId, newBaseTxnId, projectRefid, transactions, clientTrackingCode)任何异常则发送ErrorResponse并携带错误消息。其中updateProjectXml()的实现位于 ProjectFileUpdater.kt它创建一个内存 H2 数据库jdbc:h2:mem:...作为临时项目库用XmlProjectImporter导入 XMLprojectDatabase.applyUpdate(listOf(updates), 0, 1)应用日志再经GanttXMLSaver序列化回 XML 字符串。测试ProjectFileUpdaterTest.kt中的empty xlog用例验证了空日志应原样返回 XMLapply task name change用例则验证把Task1改名为Task2后生成的 XML 确实包含新名字。6.2 快照、事务日志与基线的数据模型结合StorageApi接口StorageApi.kt可以看出存储层的完整职责initProject(projectRefid)为项目克隆 schemagetProjectSnapshot(projectRefid, baseTxnId)读取快照baseTxnId为空时取MAX(base_txn_id)的最新快照insertActualSnapshot(projectRefid, baseTxnId, projectXml)写入新快照insertXlogs(...)/getTransactionLogs(...)追加/读取事务日志按base_txn_id, log_record_num排序insertTask(...)把任务写入项目 schema 的Task视图。这套快照追加日志的模型保证任意时刻项目的 XML 都可以由某个基线的快照之后的日志确定性重建这正是离线客户端最终能收敛到一致状态的基础。PluggableStorageApi提供了依赖注入式的实现便于在单元测试中替换存储行为ProjectFileUpdaterTest.kt中的buildProjectXml测试即用它模拟日志源。七、冲突合并原理列族与并发事务检测Colloboque 处理两个客户端并发修改同一任务的策略分为两层。第一层列族降低冲突概率。如第三节所述任务属性被拆入TaskName、TaskDates、TaskCostProperties、TaskClassProperties、TaskIntProperties、TaskTextProperties多张物理表。于是客户端 A 改任务颜色、客户端 B 改任务工期这类修改落在不同的物理行上两笔事务可以无冲突地并发提交。第二层PostgreXlogMerger做冲突检测。PostgreXlogMerger.kt 的类注释说明了思想检查把两个并发事务日志应用到同一基线快照是否产生冲突。流程是createProjectSnapshotDatabase(projectXml)利用PostgresConnectionFactory.createTemporaryDataSource()从模板库CREATE DATABASE ... TEMPLATE project_database_template克隆一个临时数据库再导入给定的项目 XML 作为基线状态tryMergeConcurrentUpdates(...)在临时库中打开两个独立连接都设置TRANSACTION_REPEATABLE_READ隔离级别在两个协程中并行执行服务器事务与客户端事务各自用generateSqlStatement生成并执行 SQL两个事务都执行成功后尝试提交先提交服务器事务再提交客户端事务。若任一执行或提交失败例如MERGE_TXN_TIMEOUT_MS 1000L超时或可重复读隔离级别下检测到行级冲突则回滚并返回false表示客户端修改与服务器状态冲突、必须拒绝。注释明确写道日志在两条并发事务中执行若两者都成功完成我们认为没有冲突可以合并客户端变更否则客户端变更与服务器冲突必须被拒绝。测试 ProjectFileUpdaterTest.kt 中有三组用例精确验证了这一行为测试需本地 PostgreSQL连接参数与 README 一致localhost:5432/postgres空密码测试场景期望结果merge concurrent updates fails客户端与服务器同时改同一任务的 name合并失败assertFalsemerge concurrent updates succeeds with column families客户端改duration服务器改name不同列族合并成功assertTruemerge concurrent updates succeeds客户端改name服务器插入新任务合并成功assertTrue这三组用例恰好对应第一节 DesignDoc 中的合并目标不同列上的修改可以并行合并真正写同一列同一物理行的并发修改才会被拒绝——这从测试层面印证了添加新任务是当前可安全支持的操作类型。八、存储与语句生成SQL 层的可验证细节为了让上述机制可复现仓库提供了语句生成层面的单元测试 SqlStatementsGeneratorTest.kt验证generateSqlStatement()对四类操作 DTO 的 SQL 产出InsertOperationDto→insert into table (cols) values (vals)含null值处理UpdateOperationDto带updateBinaryConditions如Triple(id_column, BinaryPred.EQ, some_id)→update table set col val where ...DeleteOperationDto→delete from table [where ...]无条件时删除全表MergeOperationDto→ PostgreSQL 的merge into ... when matched then update ... when not matched then insert ...。同文件的inserting task gives valid transaction用例还验证了一个关键性质把任务写入ProjectDatabase后取出的单条事务日志重新执行生成的 SQL能还原出完全相同的任务行包括日期格式转换的一致性——这意味着 xlog 是可重放的replayable服务器端快照日志重建 XML的可靠性由此得到保证。客户端侧的存储实现SqlProjectDatabaseImpl、Xlog.kt、H2TaskUpdateBuilder.kt等位于 ganttproject/src/main/java/net/sourceforge/ganttproject/storage是 xlog 产生端与之配套的ProjectDatabaseTest位于 ganttproject/src/test/java/biz/ganttproject/storage/ProjectDatabaseTest.kt。感兴趣可继续深入。九、小结与当前能力边界Colloboque 为 GanttProject 提供了一条完整的实时协作开发链路构建cd .. gradle publishtomavenlocal本地发布共享库版本号YY.MM.DD再gradle -Pgpr.user... -Pgpr.key... build构建 Colloboque数据库Docker 启动 PostgreSQL执行 init-colloboque-server.sql 完成 master 库、模板库与dev_all_projects库的初始化运行服务器gradle runHTTP 9000 / WebSocket 9001--help可查看全部参数运行客户端GanttProject 主工程gradle run开启enable_colloboque属性后自动连接localhost:9000并加载测试文档同步机制客户端把撤销事件转化为 xlog 事务经 WebSocket 提交服务端以baseTxnId串行校验并提交通过快照日志重建 XML 并广播给订阅者冲突处理靠列族拆表降低并发冲突概率靠PostgreXlogMerger在临时库中并行执行两笔事务检测真正的行级冲突。需要明确的能力边界README 声明当前支持的服务端更新类型为添加新任务服务器开发版以超级用户连接 PostgreSQLPostgres.kt 中有TODO: replace the user注释generateNextTxnId目前只是简单递增ColloboqueServer.kt中有TODO标注HTTP 端点的projectRefid也未做转义TODO: escape projectRefid。这些标注共同说明Colloboque 是一个仍在演进中的开发型服务本文所述流程适用于本地开发与协议验证而非生产部署。赞分享桌面应用企业应用【免费下载链接】ganttprojectOfficial GanttProject repository.项目地址https://gitcode.com/gh_mirrors/ga/ganttproject点击查看免费下载相关推荐Colloboque 设计解析GanttProject 云端的实时协作与离线合并协议Colloboque 设计解析GanttProject 云端的实时协作与离线合并协议导读 Colloboque 是 GanttProject 官方的实时协作桌面应用企业应用如何使用React Native Background Timer实现跨平台后台定时任务如何使用React Native Background Timer实现跨平台后台定时任务 React Native Background Timer是一款强大的大麦抢票脚本怎么用大麦智能抢票系统完整配置指南大麦抢票脚本怎么用大麦智能抢票系统完整配置指南很多人问大麦抢票脚本怎么配置。大麦智能抢票系统是一个 Python 自动化购票工具填好目标演出、观演人、日期GUI 自动化RPA上一篇Exposed 事务Transactions完全指南transaction / suspendTransaction 用法、嵌套事务、Savepoint 与高级参数解析下一篇Duende.IdentityServer.Admin API完全指南端点、认证与权限控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

GanttProject Colloboque 实时协作服务器：从构建、运行到同步协议解析

相关推荐

游戏时长谁说了算？服务器权威时间与客户端对时机制拆解

基于YOLOv8的路面裂缝检测系统完整实现指南

AI如何通过Mod读懂游戏设计：差分信号与数据管线的价值

更多资讯

微信小程序投票系统怎么从零搭建？以活动评选为例的完整流程

T型三电平逆变器VSG自适应控制与并离网切换优化

COMSOL电弧熔池耦合仿真技术与焊接工艺优化

外贸找客户别再手扒谷歌地图了：我用一个 AI 专家一句话拿到海外商户名单

《小王子》第十六章的文学分析与哲学启示

用电器分析识别装置：电流波形特征提取与分类器实战

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？