Ubuntu 22.04 安装 OneDev 16.9.3 指南
在 Ubuntu 22.04 服务器从零安装 OneDev 16.9.3：在线/离线双方案、初始化向导、systemd 托管、JVM 内存配置、数据库切换、备份恢复、升级与卸载全流程实测。
Ubuntu 22.04 安装 OneDev 16.9.3 指南
> 目标：在 Ubuntu 22.04 服务器上从零安装并运行 OneDev 16.9.3，覆盖在线与离线两种安装方案、JVM 内存配置、数据库切换、备份恢复、升级与卸载的完整生命周期。全文命令与回显均在 Ubuntu 22.04 环境实测通过。
一、环境信息
本文实测环境与安装目标：
- 操作系统：Ubuntu 22.04.5 LTS（x86_64，实测
PRETTY_NAME="Ubuntu 22.04.5 LTS"） - OneDev：16.9.3（2026-10-17 发布，发行包内
release.properties记录version=16.9.3） - 安装目录：
/opt/onedev - 服务端口：HTTP
6610、SSH6611（Git over SSH）、集群通信5710 - 运行用户：
root（生产可用专用用户，见第七章RUN_AS_USER说明）
二、前置条件
OneDev 服务端对系统的要求很少：Java 17+、Git 2.11.1+、curl，其余全部由发行包自带。官方口径 2 核 2GB 内存即可流畅运行，磁盘按数据增长预留（起步 20GB）。
2.1 安装系统依赖
Ubuntu 22.04 实测执行：
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
⚠️ 注意：OneDev 16.9.x 的引导配置强制要求 Java ≥ 17（发行包
conf/wrapper.conf中wrapper.java.version.min=17），Ubuntu 22.04 默认仓库的openjdk-17-jdk-headless正好满足；Java 11 会导致启动失败。
2.2 端口规划
默认使用三个端口，部署前确认空闲：
| 端口 | 用途 |
|---|---|
| 6610 | Web UI 与 REST/GraphQL API |
| 6611 | 内嵌 SSH 服务（Git over SSH、远程命令） |
| 5710 | 集群与构建 agent 通信 |
实测检查命令（空闲时无输出即可）：
ss -lntp | grep -E ':6610|:6611|:5710'
若服务器启用防火墙，放行 Web 端口（按实际网络策略执行）：
sudo ufw allow 6610/tcp
sudo ufw allow 6611/tcp
三、版本选型说明
OneDev 发版频率很高（实测官方 Releases：2026-10-02 至 10-17 的 16 天内连续发布 v16.8.3 到 v16.9.3 共 10 个版本），选型要点：
- 生产固定版本号：本文选定 16.9.3（写作当日最新版），升级节奏建议按月评估，升级前先备份；
- 形态选择：官方支持三种部署形态——虚拟机/裸金属发行包（本文）、官方镜像编排（见《OneDev Docker Compose 部署指南》）、Kubernetes Chart；单机与中小规模选发行包最直接；
- 版本查询命令：安装完成后用
cat /opt/onedev/release.properties核对实际版本，避免凭记忆假设。
四、在线安装方案（A：官方发行包，推荐）
适用：服务器可访问官方下载源。该方案是官方安装文档的推荐路径，全程五步。
4.1 下载发行包
官方安装页（docs.onedev.io/installation-guide/run-on-bare-metal）提供 onedev-latest.zip 与 onedev-latest.tar.gz 两个发行包。下载到 /opt 准备解压：
cd /opt
sudo wget -c <官方安装页提供的 onedev-latest.tar.gz 链接>
⚠️ 注意：官方下载直链在发版日前后偶有切换（本文写作当日实测直链返回 404，官方安装页仍在正常提供下载入口）。以官方安装页页面上当前给出的链接为准；内网隔离环境直接走第五章离线方案。
4.2 解压安装
发行包解压后是一个 onedev-<版本> 目录，将其规整到 /opt/onedev 并保证运行用户有完全读写权限：
sudo mkdir -p /opt/onedev
sudo tar xzf onedev-latest.tar.gz -C /opt/onedev --strip-components=1
sudo chown -R $(whoami) /opt/onedev
核对发行包结构（实测 ls /opt/onedev）：
3rdparty-licenses bin boot conf incompatibilities lib license.txt logs readme.txt
安装完成后核对版本（实测）：
$ cat /opt/onedev/release.properties
#Sat Oct 17 00:50:59 UTC 2026
date=2026-10-17 00\:50\:59
commit=47d730d4798dd94aeaa176ec113e943d2eac76f3
version=16.9.3
4.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
4.4 初始化向导
浏览器打开 http://<服务器IP>:6610，按向导完成三项设置：
- 管理员账号：登录名、密码、邮箱（本文示例使用
admin）； - 数据库：试用保持默认内嵌数据库；生产选择 MySQL/PostgreSQL/MariaDB 并填连接信息（切换原理见第九章）；
- 服务器 URL：填
http://<服务器IP>:6610，与实际访问地址一致，否则页面显示的 Git clone 地址与 Webhook 回调地址会错。
4.5 安装验证
服务存活（实测）：
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6610
200
端口监听（实测，初始化完成后的状态）：
$ ss -lntp | grep -E ':6610|:6611|:5710'
LISTEN 0 50 *:6610 *:* users:(("java",pid=2317,fd=356))
LISTEN 0 100 *:5710 *:* users:(("java",pid=2317,fd=370))
LISTEN 0 50 *:6611 *:* users:(("java",pid=2317,fd=393))
💡 实测发现的细节：6611（SSH）在完成初始化向导之前不会监听——全新实例只有
6610与5710在 LISTEN，向导走完 SSH 端口才出现。若你刚装完发现 6611 没起来，先检查是否完成了初始化，这不是故障。
管理脚本可用性（实测 server.sh 无参调用的用法提示，即完整子命令清单）：
$ /opt/onedev/bin/server.sh
Wrapper: Usage: server console|start|stop|restart|status|install|remove|dump
服务运行中执行状态检查（实测）：
$ /opt/onedev/bin/server.sh status
RUNNING
五、离线安装方案（B：断网服务器）
适用：生产内网无法直连官方下载源。思路是「有网机器获取发行包 → 传输到内网 → 同方案 A 安装」。OneDev 发行包自包含（含全部依赖 jar），离线安装与在线安装无任何差别。
5.1 有网机器获取发行包
在有外网的机器上，从官方安装页下载 onedev-latest.tar.gz（或指定版本包），并记录文件大小用于传输后校验：
ls -l onedev-latest.tar.gz
5.2 传输与完整性校验
把发行包拷贝到内网服务器（U 盘、堡垒机中转、内网制品库均可），传输后在目标服务器校验文件完整可用：
# 比对两端文件大小一致
ls -l /opt/onedev-latest.tar.gz
# 压缩包可完整列出即结构未损坏（输出首行为顶层目录名）
tar tzf /opt/onedev-latest.tar.gz | head -3
实测某次校验的首行输出形态：
onedev-16.9.3/
onedev-16.9.3/license.txt
onedev-16.9.3/readme.txt
5.3 安装与启动
解压、启动、初始化与方案 A 完全一致（4.2 → 4.5 节）。唯一前置差异：内网服务器也需提前备好 Java 17 与 Git——可从 Ubuntu 安装介质/内网镜像源安装 openjdk-17-jdk-headless 与 git，版本核对命令同 2.1 节。
💡 说明：若内网连系统包源也没有，Java 与 Git 的离线包安装属于标准 Ubuntu 离线交付流程（deb 包 +
dpkg -i），不在本文展开；确认java -version与git --version输出达标后再进入 OneDev 安装。
六、多方案对比与选择建议
| 维度 | 方案 A：在线发行包 | 方案 B：离线发行包 |
|---|---|---|
| 适用网络 | 可访问官方下载源 | 内网隔离 |
| 安装步骤 | 下载→解压→启动 | 外部获取→传输校验→解压→启动 |
| 版本控制 | 下到什么装什么（建议改名为带版本文件留存） | 发什么装什么，天然固定 |
| 后续升级 | 直接在线下载新发行包 | 需重新走离线获取流程 |
| 依赖准备 | apt 在线装 Java17/Git | 需预先备齐离线依赖 |
选择建议：能出网选方案 A（升级路径最短）；等保/隔离环境选方案 B，并把每个用过的发行包在内部制品库留档，形成「版本资产」。若组织标准是镜像化交付，直接采用《OneDev Docker Compose 部署指南》的编排方式，数据目录与升级策略见该篇。
七、systemd 服务托管
OneDev 的管理脚本原生支持注册为系统服务。server.sh 的完整子命令为（实测原文）：console|start|stop|restart|status|install|remove|dump，其中：
console：前台运行，日志直出终端，适合首次安装观察；start：守护进程方式启动（实测进程形态为wrapper-linux-x86-64 daemon /opt/onedev/conf/wrapper.conf）；status/stop/restart：日常状态管理（status实测返回RUNNING）；install/remove：注册/卸载系统服务，实现开机自启。
以守护进程方式日常运行（无需 systemd，实测可用）：
sudo /opt/onedev/bin/server.sh start # 启动
sudo /opt/onedev/bin/server.sh status # 应输出 RUNNING
sudo /opt/onedev/bin/server.sh stop # 停止
注册开机自启服务（官方流程）：
- 以专用用户运行时，编辑
/opt/onedev/bin/server.sh，取消注释并填写RUN_AS_USER行（实测脚本头部原文#RUN_AS_USER=），确保该用户对/opt/onedev全目录有读写权限； - 执行注册：
sudo /opt/onedev/bin/server.sh install，随后systemctl status onedev应显示服务已加载； - 卸载服务：
sudo /opt/onedev/bin/server.sh remove。
⚠️ 注意：
install/remove依赖系统 systemd 服务管理器，需在 systemd 已启用的 Ubuntu 服务器上执行；注册后请以systemctl is-active onedev输出active作为生效标准。另外，发行包bin/下还有reset-admin-password.sh（重置管理员密码）、apply-db-constraints.sh（数据库约束维护）等运维脚本，均可在停服状态下直接执行。
八、配置说明
配置集中在 /opt/onedev/conf/（实测目录含 server.properties、hibernate.properties、wrapper.conf、logback.xml），改后重启生效（server.sh restart）。
8.1 端口与集群参数（server.properties）
实测默认值：
http_host=0.0.0.0
http_port=6610
ssh_port=6611
cluster_port=5710
http_host：监听地址，0.0.0.0表示所有网卡（注释注明 127.0.0.1 始终会被绑定，供内部调用）；http_port/ssh_port：Web 与 SSH 端口，按需修改；server_name：集群内显示名，留空用主机名；cluster_ip/cluster_port：多实例集群通信参数，单机保持默认。
8.2 JVM 内存配置（wrapper.conf）
默认堆上限为物理内存的 50%（实测配置原文 set.default.max_memory_percent=50）。推荐改为固定值，便于容量规划。实测把堆固定在 256–512MB 的写法：
wrapper.java.initmemory=256
wrapper.java.maxmemory=512
重启后核对实际生效值（实测 ps -ef | grep [j]java，长参数节选）：
root 968 945 2 11:42 ? 00:01:32 java ... -Xss1024k -Xms256m -Xmx512m -cp /opt/onedev/boot/wrapper.jar:... io.onedev.wrapper.WrapperSimpleApp io.onedev.commons.bootstrap.Bootstrap
-Xms256m -Xmx512m 出现在进程命令行即配置生效。1GB 内存小机型可把 maxmemory 降到 256（官方文档同口径建议）；大内存机器维持百分比默认即可。
8.3 数据库切换（hibernate.properties）
默认内嵌 HSQLDB（实测配置段）：
hibernate.dialect=org.hibernate.dialect.HSQLDialect
hibernate.connection.driver_class=org.hsqldb.jdbc.JDBCDriver
hibernate.connection.url=jdbc:hsqldb:file:${installDir}/internaldb/onedev;hsqldb.tx=mvcc;hsqldb.lob_compressed=true;hsqldb.lob_file_scale=4;sql.ignore_case=true;shutdown=true
hibernate.connection.username=sa
hibernate.connection.password=
切换到外接库的标准流程（官方文档口径，实测验证过备份/恢复环节）：
- 停服：
/opt/onedev/bin/server.sh stop； - 备份：
/opt/onedev/bin/backup-db.sh /path/to/backup.zip（用法与实测输出见第九章）； - 编辑
hibernate.properties：注释 HSQLDB 段，解注释目标数据库段并填连接信息； - 在数据库侧创建空库（账号需建表权限）；
- 恢复：
/opt/onedev/bin/restore-db.sh /path/to/backup.zip； - 起服并全站验证。
⚠️ 注意：
hibernate.properties中的${installDir}是启动时由服务端替换的内置变量，不要手工赋值。
九、备份与恢复
9.1 数据库备份（backup-db.sh）
路径参数必填，实测无参执行的报错与用法提示：
$ /opt/onedev/bin/backup-db.sh
13:21:28 ERROR - Missing backup file parameter. Usage: backup-db.sh <path to database backup file>
带路径执行（实测输出尾部）：
$ /opt/onedev/bin/backup-db.sh /opt/onedev/db-backup/backup-$(date +%Y%m%d%H%M%S).zip
13:21:57 INFO - Exporting table 'EntityIdCounter'...
13:21:57 INFO - Converting table rows to XML...
13:21:57 INFO - Writing resulting XML to file 'EntityIdCounters.xml...
13:21:57 INFO -
13:21:57 INFO - Database is successfully backed up to /opt/onedev/db-backup/backup-20261017212150.zip
13:21:57 INFO - Stopping application...
⚠️ 注意两点：脚本执行完会自动停止应用（尾部
Stopping application...是脚本自身行为，重新server.sh start即可）；备份包只含数据库，Git 仓库、构建日志与附件在site/目录，完整灾备 = 备份 zip + site 目录打包，两者一起异地存放。
9.2 数据库恢复（restore-db.sh）
在目标实例停服状态下执行（实测恢复日志尾部）：
$ /opt/onedev/bin/restore-db.sh /opt/onedev/db-backup/backup-20261017190000.zip
INFO - Importing from data file 'IssueWatchs.xml'...
INFO - Importing from data file 'AccessTokens.xml'...
INFO - Importing from data file 'PullRequestTouchs.xml'...
INFO - Applying foreign key constraints...
INFO - Database is successfully restored from /opt/onedev/db-backup/backup-20261017190000.zip
INFO - Stopping application...
实测验证过跨实例搬家：把实例 A 的备份包放入实例 B 的 db-backup/ 后执行恢复，实例 B 启动后项目、构建历史、账号完整可见。该机制同时是「内嵌库 → 外接库」迁移的搬运通道（配合 8.3 节）。
十、常见问题
Q1：安装完 6611 端口没有监听？
正常现象。实测发现 6611（SSH）在完成初始化向导前不监听，全新实例只有 6610 与 5710 在 LISTEN；走完 4.4 节向导后再看 ss -lntp，6611 会出现。
Q2：忘记管理员密码怎么办？
停服后执行发行包自带脚本重置：sudo /opt/onedev/bin/reset-admin-password.sh，按提示输入登录名与新密码，重启生效。
Q3：启动即退出，日志报 Java 版本问题？
检查 java -version 是否 ≥ 17（发行包 wrapper.conf 中 wrapper.java.version.min=17 为硬性下限）。Ubuntu 22.04 用 openjdk-17-jdk-headless 安装后重试。
Q4：官方下载直链 404？
发版日前后直链可能切换，以官方安装页（docs.onedev.io/installation-guide/run-on-bare-metal）当前提供的 onedev-latest.zip/onedev-latest.tar.gz 链接为准；内网环境走离线方案。
Q5：项目多了以后报 too many open files？
运行 OneDev 的用户文件句柄配额不足，提高 ulimit（如 nofile 65535）后重启服务；官方文档在安装指南中同样给出此提示。
Q6：server.sh 子命令记不住？
直接无参执行即可看到完整清单（实测）：Wrapper: Usage: server console|start|stop|restart|status|install|remove|dump。
十一、卸载与清理
按服务注册状态二选一：
- 已注册系统服务的先卸载服务：
sudo /opt/onedev/bin/server.sh remove； - 停止进程：
sudo /opt/onedev/bin/server.sh stop，确认status不再返回RUNNING。
删除安装目录前先归档数据（备份 zip + site 目录），避免误删生产资产：
sudo tar czf /root/onedev-final-$(date +%F).tgz -C /opt/onedev site db-backup conf
sudo rm -rf /opt/onedev
如不再使用，可卸载系统依赖（可选）：
sudo apt-get remove -y openjdk-17-jdk-headless
十二、参考链接
- 官方安装指南（虚拟机/裸金属）：https://docs.onedev.io/installation-guide/run-on-bare-metal
- 系统要求：https://docs.onedev.io/installation-guide/system-requirement
- 官方网站与文档站：https://onedev.io / https://docs.onedev.io
- 源码仓库：https://github.com/theonedev/onedev
- 相关篇目：《OneDev 介绍与选型指南》《OneDev 16.9.3 核心原理详解》《OneDev Docker Compose 部署指南》
- 相关文档：《Kestra 2.0.6 Ubuntu 22.04 安装指南》《Forgejo 16.0 Docker Compose 部署指南》