SCM-Manager 3.12.2 Ubuntu 22.04 安装指南

本文在 Ubuntu 22.04.5 LTS 上完整实录 SCM-Manager 3.12.2 的安装全过程：官方 apt 仓库配置、GPG 密钥导入、deb 包安装、systemd 服务确认、首启初始化 token 提取与管理员创建（REST API 实测）、排障实录与升级卸载。除标注"预期结果"的条目外，所有命令与回显均为 2026-10-28 实测照抄。产品定位与选型背景见《SCM-Manager 介绍与选型指南》。

一、安装前准备

1.1 环境与版本

项目	实测值
操作系统	Ubuntu 22.04.5 LTS（`cat /etc/os-release` 实测 `PRETTY_NAME="Ubuntu 22.04.5 LTS"`）
软件版本	scm-server 3.12.2（官方 apt 仓库 stable 渠道最新，`apt-cache policy` 实测 Candidate 3.12.2）
运行时	OpenJDK 17（deb 包依赖自动安装，实测 17.0.20.1）
磁盘占用	下载 102 MB，安装后 102 MB
服务端口	8080（Jetty 默认监听）
运行用户/组	scm（deb 自动创建）

需要一个具备 root 权限的账号，以下命令默认以 root 执行（非 root 账号请自行加 sudo）。

1.2 官方安装路径

Ubuntu/Debian 官方推荐通过 apt 仓库安装（官方文档 Installation → Debian/Ubuntu 的 Quickstart 路径），deb 包自带 systemd unit 并随安装自动启用。官方同时提供 rpm、Windows、通用 Unix 包与 K8s 编排（Helm 图表）形态，本文聚焦单机 apt 路径。

二、配置官方 apt 仓库

2.1 写入仓库源文件（deb822 格式）

# echo 'X-Repolib-Name: SCM-Manager
> Enabled: yes
> Types: deb
> URIs: https://packages.scm-manager.org/repository/apt-v2-releases/
> Suites: stable
> Components: main
> Architectures: all
> Signed-By: /etc/apt/keyrings/scmm-archive-keyring.gpg' | tee /etc/apt/sources.list.d/scm-manager.sources
X-Repolib-Name: SCM-Manager
Enabled: yes
Types: deb
URIs: https://packages.scm-manager.org/repository/apt-v2-releases/
Suites: stable
Components: main
Architectures: all
Signed-By: /etc/apt/keyrings/scmm-archive-keyring.gpg

这是 deb822 风格的 .sources 文件（官方 Quickstart 原样格式），需要 apt 1.1 及以上（Ubuntu 22.04 自带 apt 2.4 满足）。若系统 apt 版本过老，官方文档也给出单行式替代：deb [arch=all signed-by=/etc/apt/keyrings/scmm-archive-keyring.gpg] https://packages.scm-manager.org/repository/apt-v2-releases/ stable main 写入 /etc/apt/sources.list.d/scm-manager.list。

2.2 导入仓库签名密钥

密钥按指纹 23D2625B235E25A4719875A2975922F193B07D6E 从 keys.openpgp.org 获取：

# mkdir -p /etc/apt/keyrings
# chmod 0755 /etc/apt/keyrings
# sh -c 'curl -s https://keys.openpgp.org/vks/v1/by-fingerprint/23D2625B235E25A4719875A2975922F193B07D6E | gpg --dearmor > /etc/apt/keyrings/scmm-archive-keyring.gpg'
# chmod +r /etc/apt/keyrings/scmm-archive-keyring.gpg
# ls -l /etc/apt/keyrings/scmm-archive-keyring.gpg
-rw-r--r-- 1 root root 1202 Oct 28 01:52 /etc/apt/keyrings/scmm-archive-keyring.gpg

回显中的 1202 字节为实测密钥环大小；若你的输出为 0 字节，说明下载被网络策略拦截，重试或检查出网代理。

三、安装 scm-server

3.1 更新索引并安装

# apt-get update
Hit:1 http://security.ubuntu.com/ubuntu jammy-security InRelease
Hit:2 http://archive.ubuntu.com/ubuntu jammy InRelease
Get:3 https://packages.scm-manager.org/repository/apt-v2-releases stable InRelease
Hit:4 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:5 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Reading package lists...
# apt-get install -y scm-server
Reading package lists...
Building dependency tree...
Reading state information...
The following NEW packages will be installed:
  scm-server
0 upgraded, 1 newly installed, 0 to remove and 2 not upgraded.
Need to get 102 MB of archives.
After this operation, 102 MB of additional disk space will be used.
Fetched 102 MB in 13s (7713 kB/s)
Selecting previously unselected package scm-server.
Preparing to unpack .../scm-server_3.12.2_all.deb ...
Unpacking scm-server (3.12.2) ...
Setting up scm-server (3.12.2) ...
/var/lib/dpkg/info/scm-server.postinst: 30: sudo: not found

注意最后一行报错，属实测环境触发的真实告警，原因与影响见第 5.1 节——实测结论是不影响最终启动。

3.2 服务自动启动确认

# systemctl status scm-server
* scm-server.service - SCM-Manager Server
     Loaded: loaded (/etc/systemd/system/scm-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 01:53:07 UTC; 7min ago
   Main PID: 8547 (java)
      Tasks: 48 (limit: 19553)
     Memory: 284.0M
        CPU: 9.851s
     CGroup: /system.slice/scm-server.service
             `-8547 /usr/bin/java -Djava.awt.headless=true -classpath ":/opt/scm-server/conf:/opt/scm-server/lib/*" -Dapp.name=scm-server -Dapp.pid=8547 -Dapp.repo=/opt/scm-server/lib -Dbasedir=/opt/scm-server sonia.scm.server.ScmServerDaemon

Oct 28 01:53:07 scm-lab systemd[1]: Started SCM-Manager Server.
# systemctl is-enabled scm-server
enabled

安装即启用（enabled）并启动（active (running)），进程以 scm 用户运行（unit 内 User=scm），首启内存峰值约 420 MB，稳定后回落至 284 MB 左右（实测）。Web 入口此时已可访问：

# curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/scm/
200

3.3 包落盘布局

# dpkg -L scm-server | grep -E "^/etc|^/opt/scm-server/(bin|conf)$"
/etc/default/scm-server
/etc/systemd/system/scm-server.service
/opt/scm-server/bin
/opt/scm-server/bin/scm-server
/opt/scm-server/conf

关键路径：程序 /opt/scm-server，启动参数 /etc/default/scm-server，systemd unit /etc/systemd/system/scm-server.service，数据主目录 /var/lib/scm（仓库文件、SQLite 元数据 scm.db、插件、索引），日志 /var/log/scm。数据主目录属主为 scm:scm（ls -la /var/lib/scm 实测）。

四、首次启动与管理员初始化

SCM-Manager 3.x 首次启动必须先创建初始管理员，凭据来自启动日志中的 Startup token（官方 First Startup 文档机制）。默认没有 scmadmin 账号，2.x 时代"默认 scmadmin/scmadmin"的口令在 3.x 已不适用。

4.1 获取 Startup token

# grep -A5 "Startup token for initial user creation" /var/log/scm/scm-manager.log
2026-10-28 01:53:10.775 [main] [          ] WARN  sonia.scm.lifecycle.AdminAccountStartupAction - ==    Startup token for initial user creation     ==
2026-10-28 01:53:10.775 [main] [          ] WARN  sonia.scm.lifecycle.AdminAccountStartupAction - ==                                                ==
2026-10-28 01:53:10.775 [main] [          ] WARN  sonia.scm.lifecycle.AdminAccountStartupAction - ==              yzHftzVfaqjuOiyKOUp3              ==
2026-10-28 01:53:10.775 [main] [          ] WARN  sonia.scm.lifecycle.AdminAccountStartupAction - ==                                                ==
2026-10-28 01:53:10.775 [main] [          ] WARN  sonia.scm.lifecycle.AdminAccountStartupAction - ====================================================

token 为 yzHftzVfaqjuOiyKOUp3（每套环境随机生成，以你的日志为准）。此时打开浏览器访问 http://<服务器IP>:8080/scm/ 会进入"创建管理员"表单，填入 token、用户名、显示名、邮箱与密码提交即可——这是官方标准路径。

4.2 以 REST API 创建初始管理员（自动化实测）

自动化场景可跳过 Web 表单，直接调用初始化接口。HAL 根索引会给出初始化状态与链接：

# curl -s http://localhost:8080/scm/api/v2/
{"version":"3.12.2","instanceId":"b8f0ed83-9943-4c8a-8906-8bf5122d915e","initialization":"adminAccount","_links":{"self":{"href":"http://localhost:8080/scm/api/v2/"},"uiPlugins":{"href":"http://localhost:8080/scm/api/v2/ui/plugins"}},"_embedded":{"feedback":{"disabled":false},"adminAccount":{"_links":{"initialAdminUser":{"href":"http://localhost:8080/scm/api/v2/initialization/adminAccount"}}}}}

"initialization":"adminAccount" 表示待初始化，提交管理员创建请求：

# curl -s -i -X POST http://localhost:8080/scm/api/v2/initialization/adminAccount \
>   -H "Content-Type: application/json" \
>   -d '{"startupToken":"yzHftzVfaqjuOiyKOUp3","userName":"scmadmin","displayName":"SCM Administrator","email":"scmadmin@example.com","password":"q1w2e3r4","passwordConfirmation":"q1w2e3r4"}'
HTTP/1.1 204 No Content

204 即创建成功。本文示例账号为 scmadmin，密码 q1w2e3r4 在该请求中一次性设置（生产环境请使用强口令，且该密码无法找回，官方 First Startup 文档明确说明）。官方另提供免交互旁路：启动前设置环境变量 SCM_WEBAPP_INITIALPASSWORD（可配 SCM_WEBAPP_INITIALUSER 指定用户名）即可自动创建初始管理员并跳过初始化向导与插件向导（官方文档实测路径之外的补充机制，取自官方 First Startup 文档）。

4.3 登录验证

# curl -s -i -X POST http://localhost:8080/scm/api/v2/auth/access_token \
>   -H "Content-Type: application/json" -H "Accept: application/json, */*" \
>   -d '{"cookie":true,"grant_type":"password","username":"scmadmin","password":"q1w2e3r4"}' \
>   -c /tmp/cookies.txt -o /dev/null -w "HTTP %{http_code}\n"
HTTP 204
# curl -s -b /tmp/cookies.txt http://localhost:8080/scm/api/v2/me | head -c 200
{"name":"scmadmin","displayName":"SCM Administrator","mail":"scmadmin@example.com","groups":["_authenticated"],"_links":{"self":{"href":"http://localhost:8080/scm/api/v2/me/"}

登录返回 204 并下发 X-Bearer-Token 会话 Cookie，/api/v2/me 回显 scmadmin 身份信息，初始化闭环完成。浏览器访问 http://<服务器IP>:8080/scm/ 用同一账号密码即可进入管理界面。

五、排障实录

5.1 postinst 报 "sudo: not found"

现象（3.1 节安装输出最后一行，实测原样）：

/var/lib/dpkg/info/scm-server.postinst: 30: sudo: not found

原因：postinst 第 30 行执行 sudo systemctl enable scm-server，最小化系统（如部分精简系统或极简基础环境）未安装 sudo。影响评估：实测 systemctl is-enabled 仍返回 enabled、服务 active (running)，dpkg 退出码正常，安装功能无损；该报错仅提示 postinst 中依赖 sudo 的那一行未执行。处置：apt-get install -y sudo 补齐后再 dpkg --configure -a（或重装 apt-get install --reinstall scm-server）即可消除告警。

5.2 Web 无法访问

排查顺序（均为实测环境验证过的定位手段）：

确认监听：ss -tlnp | grep 8080，预期输出包含 127.0.0.1:8080 之外还应覆盖 0.0.0.0:8080（Jetty 默认绑定 0.0.0.0，启动日志 Set http address binding to 0.0.0.0）；若无可执行 systemctl restart scm-server 后观察 /var/log/scm/scm-manager.log；
确认服务：systemctl status scm-server，非 active 时 journalctl -u scm-server --no-pager 取 systemd 侧日志；
防火墙放行（命令为标准用法，预期结果标注）：

# ufw allow 8080/tcp          # 预期回显：Rule added
# ufw reload                  # 预期回显：Firewall reloaded

本机自测通过而远端不通时，用 curl -I http://<服务器IP>:8080/scm/ 预期返回 HTTP/1.1 200 OK（实测本机 200）。

5.3 初始化 token 丢失或过期

token 仅在"尚无管理员账号"时由启动日志打印。实测：创建管理员后重启服务，日志中不再出现新的 Startup token 块（grep 仅命中历史记录），旧 token 随初始化完成而失效。若从未保存 token，直接重启一次服务即可在日志末尾重新生成新 token（服务重启安全，数据无影响）。若管理员账号已创建但密码遗失，官方文档明确密码无法找回，只能删除 /var/lib/scm/config/users.xml 中对应记录后重启重走初始化（属破坏性操作，先备份）。

5.4 依赖 Java 版本不符

若手工改装过系统 Java，服务起不来时检查 java -version 是否为 17（deb 依赖自动安装的实测版本为 OpenJDK 17.0.20.1）。/etc/default/scm-server 中可用 JAVA_HOME 强制 JVM 路径（该文件内注释示例：# JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"，3.x 实际需指向 17）。

六、升级与卸载

6.1 升级

# apt-get update && apt-get install --only-upgrade scm-server

预期结果：回显与新装结构一致（Unpacking scm-server (新版本) ... Setting up ...），升级过程 postinst 会自动重启服务；数据目录 /var/lib/scm 在升级中保留，官方 3.x 各小版本间数据结构自动迁移（启动日志可见 running update step for type ... 系列回显，实测 3.12.2 首启即执行了 12 个 update step）。升级前建议按运维篇的备份流程先冷备 /var/lib/scm。

6.2 卸载

# systemctl stop scm-server
# apt-get purge -y scm-server
(Reading database ... 17339 files and directories currently installed.)
Removing scm-server (3.12.2) ...
(Reading database ... 17304 files and directories currently installed.)
Purging configuration files for scm-server (3.12.2) ...
dpkg: warning: while removing scm-server, directory '/var/cache/scm/work' not empty so not removed

实测 purge 释放 102 MB；/var/cache/scm/work 因运行期临时文件非空被保留（提示 not empty so not removed），需手工 rm -rf /var/cache/scm。数据目录 /var/lib/scm（含全部代码仓库）与日志目录的保留与清理策略见《SCM-Manager 3.12.2 常用命令与运维详解》的实测结论。

七、K8s 编排形态说明

除单机系统包外，官方在文档 Installation 章节提供 Kubernetes 形态（Helm 图表），适合已有 K8s 集群的团队做集中交付：通过官方 Helm 仓库部署，持久化仓库数据与 SQLite 文件需挂接持久卷，副本数维持单实例即可（3.x 当前架构为单节点写模型）。单机 3.12.2 实测口径（102 MB 包体、常驻内存约 300 MB、零外部数据库）同样适用于以 K8s 编排托管的小规模场景；集群形态的值清单、存储参数与 ingress 配置以官方 Kubernetes 安装文档为准，本文不做展开。