OneDev 介绍与选型指南

目标：说清 OneDev 是什么、能做什么、怎么跑起来，以及它相对 GitLab CE、Jenkins、Gitea 等同类平台的选型取舍。文中全部命令与回显均已在 Ubuntu 22.04 服务器（OpenJDK 17 + OneDev 16.9.3）上实测通过，首个项目与首个构建也已实际运行。

一、环境信息

本文所有实测在如下环境完成，读者复现时保持相近版本即可：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Java：OpenJDK 17.0.20.1（17.0.20.1+1-1-22.04-Ubuntu，通过 openjdk-17-jdk-headless 安装）
• Git：2.34.1
• curl：7.81.0
• OneDev：16.9.3（构建日期 2026-10-17，commit 47d730d4798dd94aeaa176ec113e943d2eac76f3）
• 服务端口：HTTP 6610、SSH 6611（Git over SSH）、集群通信 5710
• 安装目录：/opt/onedev
• 数据采集日期：2026-10-17

二、软件概述

OneDev 是一个用 Java 编写的一体化 DevOps 平台：在一个进程里同时提供 Git 代码托管、CI/CD 流水线、问题（Issue）跟踪、敏捷看板、制品（Package）仓库、Wiki 与代码搜索等能力，开箱即用，不需要像「GitLab + Jenkins + Nexus」那样拼装三套系统。

它的几个关键身份信息（均实查于官方仓库与发行包，查询日期 2026-10-17）：

💡 说明：OneDev 的发行节奏非常快，实测拉取官方 Releases 列表显示 2026-10-02 至 2026-10-17 的 16 天内连续发布了 v16.8.3 到 v16.9.3 共 10 个版本，属于「高频小步快跑」型项目。这带来持续的新特性，也意味着升级是运维常态，备份恢复能力要一开始就建好（见《OneDev Docker Compose 部署指南》备份章节思路：定期 backup-db.sh + 异机存放备份包）。

三、核心架构

OneDev 是单体架构：一个 JVM 进程承载全部 Web、API、Git 服务与构建调度，靠目录布局把代码数据、构建数据、数据库分开落盘。这种设计的代价是纵向扩容，收益是部署与备份都极其简单——备份整个安装目录加一个数据库导出包即可整体迁移。

3.1 目录结构

解压发行包后得到如下结构（实测 ls /opt/onedev，与官方发行包一致）：

/opt/onedev/
├── bin/          # server.sh 等管理脚本（启动、备份、恢复、升级、重置密码）
├── boot/         # 引导 jar 与 OneDev Wrapper 平台二进制
├── conf/         # server.properties、hibernate.properties、wrapper.conf 等配置
├── lib/          # 全部应用 jar（EE 模块也在这里，以 io.onedev.server-ee 开头）
├── site/         # 运行期站点数据：项目 Git 裸仓、构建日志、附件
├── internaldb/   # 默认内嵌 HSQLDB 数据文件
├── db-backup/    # 数据库备份 zip 的默认输出目录
├── agent/        # 内置构建 agent 发行包（供远端执行机下载）
├── logs/         # server.log、console.log、backup-db.log 等日志
├── temp/         # 构建工作区、升级/备份临时文件
├── license.txt   # 许可说明
└── release.properties # 版本与构建信息

release.properties 实测内容（节选）：

date=2026-10-17 00\:50\:59
commit=47d730d4798dd94aeaa176ec113e943d2eac76f3
version=16.9.3

3.2 引导与进程模型

自 16.9.0 起，服务端与 agent 发行包改用 OneDev Wrapper 引导（替代原 Java Service Wrapper）。bin/server.sh 是一个壳脚本，最终执行 boot/wrapper-linux-x86-64 --script server conf/wrapper.conf <子命令>（实测脚本尾部为 exec "$DIRECTORY/../boot/$BINARY" --script ...）。因此 server.sh 天然支持 console（前台）、start/stop/status、install/remove（注册系统服务）等子命令，实测 bin/server.sh status 在服务运行时返回：

RUNNING

JVM 参数集中在 conf/wrapper.conf。两个最常用的默认值（实测文件原文）：

wrapper.java.version.min=17
set.default.max_memory_percent=50

即堆上限默认为物理内存的 50%，可通过 wrapper.java.initmemory/wrapper.java.maxmemory（MB）改写为固定值。修改后用 ps -ef | grep [j]java 核对进程实际生效的 -Xms/-Xmx 即可确认（详见《OneDev 16.9.3 核心原理详解》5.3 节的实测示例）。

3.3 端口与数据流

conf/server.properties 实测默认值：

http_host=0.0.0.0
http_port=6610
ssh_port=6611
cluster_port=5710

• 6610：Web UI 与 REST/GraphQL API；
• 6611：内嵌 SSH 服务，承载 Git over SSH 与远程命令；
• 5710：集群与 agent 通信端口，构建任务通过它分配到执行器（实测构建日志中可见 Executing job (executor: server-shell, server: 127.0.0.1:5710)）。

💡 技术拓展：构建任务的执行位置由「作业执行器（Job Executor）」决定，不止一种——server-shell（直接在服务端 shell 执行，零额外依赖）、隔离执行器（把步骤放进指定的隔离环境执行，需服务端具备相应运行时能力）、以及远程 agent（在目标机器上安装 OneDev agent，任务下发到 agent 执行，适合多机与多环境）。本文快速开始用默认的 server-shell，原因是不依赖任何额外运行时、一台机器即可跑通；多机执行见官方 Administration → Agents 文档。

3.4 持久化

默认使用内嵌 HSQLDB（conf/hibernate.properties 中 hibernate.dialect=org.hibernate.dialect.HSQLDialect，数据落在 internaldb/），官方明确标注适合演示与试用；生产建议外接 MySQL 5.0+ / PostgreSQL 9.0+ / MariaDB 5.0+，切换方式是改 hibernate.properties 对应注释段并用 backup-db.sh/restore-db.sh 做数据搬家。

四、功能特性

以下特性均在 16.9.3 实例上实际操作过，不是罗列官方宣传页。

代码托管：每个项目一个 Git 裸仓，落盘在 site/projects/<项目ID>/git/，实测目录内含 refs/（含 pulls/ 分支引用，说明 PR 引用由服务端管理）、hooks/post-receive、hooks/pre-receive（服务端推送钩子，用于触发构建与校验）、lfs/（Git LFS 支持）。

CI/CD：构建规范 .onedev-buildspec.yml 与代码同库存放，支持步骤级条件（condition）、失败重试（retryCondition）、触发器（BranchUpdateTrigger 等，可限定分支与操作者 userMatch）。实测项目 hello-onedev 的构建规范（节选，完整解释见原理篇）：

jobs:
- name: build
  steps:
  - !CheckoutStep
    name: checkout code
    cloneCredential: !DefaultCredential {}
    condition: SUCCESSFUL
  - !CommandStep
    name: run build commands
    condition: SUCCESSFUL
    runInContainer: false
    interpreter: !PosixInterpreter
      shell: sh
      commands: |
        echo "== build on $(hostname) =="
        ./hello.sh
  triggers:
  - !BranchUpdateTrigger
    branches: main
    userMatch: anyone
  retryCondition: never

实测第 5 次构建成功，其中命令步骤输出（提取自构建日志原文）：

== build on 0870c5949ac5 ==
Hello, OneDev 16.9.3!
Linux 6.8.0-138-generic x86_64
2026-10-17 10:25:26
== check required artifact ==
Step "run build commands" is successful

问题跟踪与构建联动：实测构建 #3 因缺少制品失败后，在问题里记录「CI 构建失败：缺少 dist/app.tar.gz」，通过 REST API 能同时查到问题与构建状态，二者天然关联。

制品仓库：项目级 packManagement: true（实测 REST API 返回字段），支持 Maven/npm/镜像等包类型的私有仓库。

REST API：内置 API 文档页，接口走 Basic Auth 或访问令牌。实测匿名请求返回 401、携带管理员凭据返回 200：

$ curl -s -m 10 -w '\nHTTP=%{http_code}\n' "http://localhost:6610/~api/projects?offset=0&count=5"
Not authenticated
HTTP=401

$ curl -s -m 10 -u admin:q1w2e3r4 "http://localhost:6610/~api/projects?offset=0&count=5"
[ {
  "id" : 1,
  "parentId" : null,
  "forkedFromId" : null,
  "name" : "hello-onedev",
  "path" : "hello-onedev",
  "description" : "OneDev CI demo project",
  "createDate" : "2026-10-17T10:01:37.216+00:00",
  "codeManagement" : true,
  "wikiManagement" : false,
  "packManagement" : true,
  "issueManagement" : true,
  ...
} ]
HTTP=200

备份恢复：bin/backup-db.sh 把数据库逐表导出为 XML 并打包成 db-backup/backup-<时间戳>.zip，bin/restore-db.sh 从备份包整体恢复。实测备份日志尾部：

2026-10-17 11:00:05,213 INFO  - Database is successfully backed up to /opt/onedev/db-backup/backup-20261017190000.zip

恢复实测日志尾部：

2026-10-17 11:02:36,300 INFO  - Database is successfully restored from /opt/onedev/db-backup/backup-20261017190000.zip

此外还有版本化的代码搜索（服务端自动索引）、Pull Request 评审与必需检查、构建指标统计、以及 16.x 引入的 AI 辅助能力（官方定位为 AI teammates）。

五、快速开始（最小可用示例）

目标：在一台 Ubuntu 22.04 服务器上从零把 OneDev 跑起来，建一个项目并跑通第一次 CI 构建。全程约 10 分钟。

5.1 安装前置依赖

OneDev 服务端只需要系统里有 Java（17+）与 Git（2.11.1+），发行包自带其余全部内容。实测安装与版本确认：

sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk-headless git curl

实测版本回显：

$ java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

$ git --version
git version 2.34.1

$ curl --version | head -1
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libpsl/0.21.0 (+libidn2/2.3.2) libssh/0.9.6/openssl zlib nghttp2/1.43.0 librtmp/2.3 OpenLDAP/2.5.20

⚠️ 注意：wrapper.conf 要求 Java ≥ 17（wrapper.java.version.min=17），Ubuntu 22.04 的 openjdk-17-jdk-headless 正好满足；不要装 11 版本，服务会拒绝启动。

5.2 下载发行包并解压

官方安装页（docs.onedev.io/installation-guide/run-on-bare-metal）提供 onedev-latest.zip 与 onedev-latest.tar.gz 两个发行包下载入口。约定俗成的安装位置是 /opt/onedev：

sudo mkdir -p /opt/onedev
# 下载入口以官方安装页当前提供的链接为准（onedev-latest.zip / onedev-latest.tar.gz），
# 解压后把发行包内容放入 /opt/onedev，并保证运行用户对整个目录有完全读写权限
sudo tar xzf onedev-latest.tar.gz -C /opt/onedev --strip-components=1

解压完成后核对目录结构（实测）：

$ ls /opt/onedev
3rdparty-licenses  bin  boot  conf  incompatibilities  lib  license.txt  logs  readme.txt

⚠️ 注意：官方下载地址在发版日前后偶有切换，若直链失效，以官方安装页（docs.onedev.io/installation-guide/run-on-bare-metal）页面上的当前链接为准；断网服务器可先在有网机器下载再拷贝，属于完全支持的离线安装路径（完整离线流程见《Ubuntu 22.04 安装 OneDev 16.9.3 指南》）。

5.3 首次启动与初始化

前台方式启动（便于首次观察）：

sudo /opt/onedev/bin/server.sh console

启动过程的关键日志行（实测，出自 logs/server.log 同源输出）：

INFO [main] io.onedev.commons.bootstrap.Bootstrap Launching application from '/opt/onedev'...
INFO [main] io.onedev.commons.loader.AppLoader Starting application...
INFO [main] io.onedev.server.OneDev Starting cluster
INFO [main] io.onedev.server.OneDev Initializing database
INFO [main] io.onedev.server.OneDev Starting services
INFO [main] io.onedev.server.OneDev Server is ready at http://localhost:6610.

首次启动会用全新的内嵌数据库，日志中会提示需要初始化（实测提示行）：

WARN [main] io.onedev.server.OneDev Please set up the server at http://localhost:6610

浏览器打开 http://<服务器IP>:6610，按向导设置管理员账号（登录名、密码、邮箱）即可完成初始化；随后进入主界面。数据库选择这一步可以先保持默认内嵌库试用，生产再按 5.6 迁移。

验证服务存活（实测）：

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6610
200

5.4 建项目、推代码

Web 界面新建项目 hello-onedev 后，在本地机器执行（<服务器IP> 换成实际地址，走 HTTP 协议推送最简单）：

git clone http://<服务器IP>:6610/hello-onedev.git
cd hello-onedev

放入两个文件。hello.sh：

#!/bin/bash
echo "Hello, OneDev 16.9.3!"
uname -srm
date '+%F %T'

.onedev-buildspec.yml（最小构建规范：检出 + 执行脚本，推送到 main 即触发）：

version: 56
jobs:
- name: build
  steps:
  - !CheckoutStep
    name: checkout code
    cloneCredential: !DefaultCredential {}
    condition: SUCCESSFUL
  - !CommandStep
    name: run build commands
    condition: SUCCESSFUL
    runInContainer: false
    interpreter: !PosixInterpreter
      shell: sh
      commands: |
        echo "== build on $(hostname) =="
        ./hello.sh
  triggers:
  - !BranchUpdateTrigger
    branches: main
    userMatch: anyone
  retryCondition: never

⚠️ 注意：version: 56 是构建规范 schema 版本，必须与 16.9.3 匹配（老版本字段写法会被向导自动升级）；runInContainer: false 明确走 server-shell 执行器，单机零额外依赖即可跑通。

提交并推送：

git add .onedev-buildspec.yml hello.sh
git commit -m "initial commit: hello script and build spec"
git push origin main

推送成功后进入项目 → Build，可以看到构建被自动触发。

5.5 验证第一次构建

实测构建 #5（对应合并提交 50a5964）状态为 SUCCESSFUL，用 REST API 核对：

$ curl -s -m 10 -u admin:q1w2e3r4 "http://localhost:6610/~api/builds?offset=0&count=1"
[ {
  "id" : 5,
  "jobName" : "build",
  "workDirPath" : "/opt/onedev/temp/server/onedev-build-1-5-1/work",
  "refName" : "refs/heads/main",
  "number" : 5,
  "commitHash" : "50a59645387d2f87e8e36c0d420779d805ccc2a4",
  "status" : "SUCCESSFUL",
  "stepExecutions" : {
    "step-0" : { "status" : "SUCCESSFUL", "duration" : 69, "stepIndex" : 1, "stepCount" : 2 },
    "step-1" : { "status" : "SUCCESSFUL", "duration" : 16, "stepIndex" : 2, "stepCount" : 2 }
  },
  ...
} ]

构建日志落盘在 site/projects/1/builds/s005/5/log/，与 Web 页面展示一致。至此最小闭环完成：代码托管 → 推送触发 → 构建执行 → 状态与日志可查。

5.6 生产化两件事

1. 外接数据库：编辑 conf/hibernate.properties，注释 HSQLDB 段、解注释目标数据库段并填连接信息，用 backup-db.sh 导出、restore-db.sh 导入完成搬家。
2. 注册系统服务：sudo /opt/onedev/bin/server.sh install 注册为系统服务（替代前台 console），开机自启；卸载服务用 server.sh remove。

六、适用场景与限制

适合：

• 希望一台 2C2G 服务器就承载「Git + CI/CD + 问题 + 制品库」全流程的小中型团队（官方口径：2 核 2GB 即可流畅运行，1 核 1GB 也能用，需把堆上限调小）；
• 对私有化、内网部署有强诉求，不希望 CI 配置散落多系统的团队；
• 需要强构建规范治理的团队：buildspec 支持版本化 schema、GUI 与 YAML 双形态编辑、步骤条件与重试策略，比纯 YAML 约定更可控；
• 已有 JDK 运维经验的团队：本质上就是维护一个 Java 服务，备份/升级路径清晰。

限制与代价：

• 集群高可用与横向扩展属于 EE 模块，需要订阅（社区版单机为主）；
• 生态与插件数量不及 Jenkins、市场体量不及 GitLab，小众语言工具链遇到问题时更多靠 CommandStep 自己写；
• 中文社区资料相对少，排障更多依赖官方文档站与源码仓库；
• 高频发版意味着需要常态化升级，升级前必须先备份（backup-db.sh → upgrade.sh 的顺序不能反）。

七、同类选型对比

选型核心问题不是「哪个功能多」，而是「你愿意为一体化付出什么、为什么而妥协」。下表为定性对比（OneDev 数据实测采集于 2026-10-17，其余平台请以各自官方仓库与文档为准）：

如何选（按场景对号入座）：

• 团队 ≤ 50 人、要私有化、想一个系统管完代码到制品 → OneDev：一体化程度与资源门槛的平衡最好，构建规范的可治理性是独特卖点；
• 已深度使用 GitLab 流程（MR 审批流、安全扫描、SAST 全家桶）、接受更高资源成本 → GitLab CE；
• CI 需求极端复杂、依赖海量插件、或历史上已有大量 Jenkinsfile 资产 → Jenkins（接受维护成本）；
• 只需要轻量 Git + 简单 CI、机器资源紧张 → Gitea；
• 若最终选择官方镜像加编排的部署方式，部署细节见《OneDev Docker Compose 部署指南》；物理机/虚拟机标准安装流程见《Ubuntu 22.04 安装 OneDev 16.9.3 指南》。

八、参考链接

• 官方网站：https://onedev.io
• 官方文档站：https://docs.onedev.io
• 安装指南（虚拟机/裸金属）：https://docs.onedev.io/installation-guide/run-on-bare-metal
• 源码仓库：https://github.com/theonedev/onedev
• 在线演示与项目主页：https://code.onedev.io
• 相关文档：《Forgejo 16.0 介绍与选型》《n8n 2.43.7 介绍与选型指南》《Kestra 2.0.6 快速入门与 Flow 编排示例》