Ubuntu 22.04 安装 OpenCloud 指南

Ubuntu 22.04 以官方单二进制安装 OpenCloud 8.1.0：官方一键脚本与手动安装双方案、opencloud init、opencloud.env 环境变量、systemd 托管、Web 登录与 WebDAV 上传下载闭环全量实测，含升级、多版本管理与六条排障实录。

OpenCloudOpenCloud文件共享文件存储Go2026/10/22

Ubuntu 22.04 安装 OpenCloud 指南

目标：在 Ubuntu 22.04 服务器上从零安装 OpenCloud 8.1.0（ownCloud Infinite Scale 的社区延续版，Go 单二进制、无外部数据库依赖），覆盖官方一键脚本与手动二进制两种安装方案、opencloud init 初始化、环境变量文件与 systemd 托管、Web 登录与 WebDAV 上传下载闭环验证，以及升级、排障与卸载。本文全部命令与回显均于 2026-10-22 在 Ubuntu 22.04 真实服务器上逐条实测，输出逐行照抄。

一、环境信息

本章列出实测环境的软件与路径信息，后文所有命令均在此环境执行并可复现。

项目值
操作系统Ubuntu 22.04（x86_64）
OpenCloud 版本8.1.0（Edition: rolling，2026-10-05 编译，官方最新稳定版）
二进制路径/usr/local/bin/opencloud（单文件，约 133 MB）
配置目录/etc/opencloud/config/（含 opencloud.yaml，由 opencloud init 生成）
数据目录/var/lib/opencloud/（含 idm/idp/nats/proxy/search/storage 六个子目录）
环境变量文件/etc/opencloud/opencloud.env（由本文创建，systemd 通过 EnvironmentFile 加载）
systemd 服务/etc/systemd/system/opencloud.service
对外端口9200/TCP（HTTPS，由内部 proxy 服务统一承接 Web/WebDAV/OIDC）
管理员账号admin / q1w2e3r4
服务器地址10.89.56.2（示例内网地址，实际以你的服务器 IP 为准，需与 OC_URL 一致）

💡 说明：OpenCloud 与 ownCloud Infinite Scale（oCIS）同源——它是在 Kiteworks 收购 ownCloud 后，由原 oCIS 核心团队在 Heinlein Group 支持下于 2024 年底成立的社区分支，环境变量体系（OC_* 前缀）、目录布局与 oCIS 高度一致。背景与选型对比见本专栏认知篇。

二、前置条件

安装前确认服务器满足以下条件，逐项给出实测检查命令与回显。

2.1 系统与依赖

OpenCloud 是 Go 编译的静态单二进制，无运行时依赖，只需基础的下载工具与 CA 证书：

$ cat /etc/os-release | grep PRETTY
PRETTY_NAME="Ubuntu 22.04.5 LTS"
$ apt update && apt install -y curl ca-certificates

curl 用于下载二进制与后续验证；ca-certificates 保证 HTTPS 下载源可信。实测环境中 curl 版本：

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

2.2 端口规划

OpenCloud 默认以 9200/TCP（HTTPS） 作为唯一对外入口（proxy 服务），内部微服务全部监听在 127.0.0.1 的 9140–9282 高位端口段（实测 ss -ltnp 输出，见第五章 5.6 节），无需防火墙放行。若服务器启用 ufw，放行 9200 即可：

$ ufw allow 9200/tcp

⚠️ 注意：不要把 proxy 入口改到 9210 等端口——内部服务（如 userlog 默认绑 127.0.0.1:9210）会与之冲突导致启动失败，实测 fatal 见第十章 Q6。生产建议保持 9200 入口不变。

2.3 访问地址确认

OC_URL 必须使用 https:// 前缀并指向服务器的实际访问地址（IP 或域名），浏览器、桌面客户端与 API 都通过该地址访问。配置前先确认服务器 IP：

$ ip -4 addr show | grep inet | grep -v 127.0.0.1
inet 10.89.56.2/24 ...

本文以 https://10.89.56.2:9200 为例，替换为你的实际地址即可。

三、版本选型说明

OpenCloud 发布节奏较快（几乎每月一个稳定版），选型时认准 GitHub Releases 上的最新稳定 tag。截至 2026-10-22 查询 GitHub Releases（https://github.com/opencloud-eu/opencloud/releases），最近版本序列如下：

版本发布日期
8.1.02026-10-05
8.0.02026-09-15
7.2.42026-08-21
7.2.32026-08-06
7.4.02026-08-03

本文选用 8.1.0（最新稳定版）。各版本通用下载地址模式为：

https://github.com/opencloud-eu/opencloud/releases/download/v<版本>/opencloud-<版本>-linux-amd64

即 8.1.0 的完整下载 URL 为 https://github.com/opencloud-eu/opencloud/releases/download/v8.1.0/opencloud-8.1.0-linux-amd64。版本号获取命令（不硬编码未来版本，随官网实查为准）：

$ curl -s https://api.github.com/repos/opencloud-eu/opencloud/releases/latest | grep '"tag_name"'

⚠️ 注意：GitHub API 对匿名请求限流（按出口 IP 每小时 60 次），限流时该命令返回 API rate limit exceeded 的 JSON 而非版本号，可直接打开 Releases 页面确认。x86_64 之外还有 arm64 构建（把 URL 中 amd64 换成 arm64）。

四、方案 A：官方一键脚本安装（快速体验）

官方文档（docs.opencloud.eu Admin Docs）给出的 Quick start 是一行命令：

$ curl -L https://opencloud.eu/install | /bin/bash

本章先把脚本取下来读懂再执行，避免"盲跑脚本"。实测（直连 opencloud.eu 被重置，走代理取回；排障见第十章 Q3）：

$ curl -fsSL -x http://192.168.1.62:7897 -o install.sh https://opencloud.eu/install
$ wc -l install.sh
119 install.sh

4.1 脚本行为解读（实测脚本内容）

脚本关键逻辑（摘自实测下载的 install.sh，119 行）：

  1. 版本探测：默认调 GitHub API 取 releases/latest，可用环境变量 OC_VERSION 指定版本（脚本头注释原文：This script supports the following environment variables: OC_VERSION: Version to download, e.g. OC_VERSION="1.2.0"）；
  2. 下载二进制到当前目录下新建的 opencloud-sandbox-<版本>/ 沙盒目录；
  3. 在沙盒目录内创建 config/ 与 data/ 两个目录，并导出 OC_CONFIG_DIR、OC_BASE_DATA_PATH 指向它们；
  4. 执行 ./opencloud-<版本>-linux-amd64 init --insecure yes --admin-password admin（管理员密码固定为 admin）；
  5. 生成同目录启动脚本 runopencloud.sh 并前台启动服务，结尾提示：
Connect to OpenCloud via https://localhost:9200

*** This is a fragile test setup, not suitable for production! ***
    If you stop this script now, you can run your test OpenCloud again
    using the script opencloud-sandbox-8.1.0/runopencloud.sh

脚本生成的 runopencloud.sh 内容（实测照抄，可据此了解该体验环境的完整变量集）：

#!/bin/bash
SCRIPT_DIR="$(dirname "$(readlink -f "${0}")")"
cd "${SCRIPT_DIR}"
export OC_CONFIG_DIR=/root/opencloud-sandbox-8.1.0/config
export OC_BASE_DATA_PATH=/root/opencloud-sandbox-8.1.0/data

export OC_INSECURE=true
export OC_URL=https://localhost:9200
export IDM_CREATE_DEMO_USERS=true
export PROXY_ENABLE_BASIC_AUTH=true
export OC_LOG_LEVEL=warning

./opencloud-8.1.0-linux-amd64 server

💡 说明：脚本明确自称 "fragile test setup, not suitable for production"——它把数据落在执行时的工作目录、密码固定为 admin、还开启 IDM_CREATE_DEMO_USERS=true（会自动创建 einstein、marie 等演示用户，实测见第十章 Q4 的演示用户列表）。适合一分钟拉起体验，不适合作为服务器正式部署。

4.2 实测执行与验证

指定版本执行脚本（规避 GitHub API 限流，同时为加速下载配置代理；no_proxy 让 API 版本探测直连）：

$ OC_VERSION=8.1.0 OC_HOST=localhost bash install.sh

实测关键输出（进度条略）：

Downloading https://github.com/opencloud-eu/opencloud/releases/download/v8.1.0//opencloud-8.1.0-linux-amd64
 generated OpenCloud Config
 configpath : /root/opencloud-sandbox-8.1.0/config/opencloud.yaml
Connect to OpenCloud via https://localhost:9200
*** This is a fragile test setup, not suitable for production! ***

脚本会阻塞在前台运行服务。此时服务已在 9200 端口就绪，验证：

$ curl -sk -o /dev/null -w "%{http_code}\n" https://localhost:9200/
200
$ curl -sk https://localhost:9200/ | grep -oE "<title>[^<]*</title>"
<title>OpenCloud</title>
$ curl -sk -u admin:admin https://localhost:9200/ocs/v1.php/cloud/user?format=json
{"ocs":{"meta":{"status":"ok","statuscode":100,"message":"OK"},"data":{"id":"admin","display-name":"Admin","email":"admin@example.org","user-type":"primary"}}}

沙盒目录结构（实测 ls）：

$ ls /root/opencloud-sandbox-8.1.0/
config  data  opencloud-8.1.0-linux-amd64  runopencloud.sh
$ ls /root/opencloud-sandbox-8.1.0/data/
idm  idp  nats  proxy  search  storage

停止体验环境：在前台按 Ctrl+C，之后可随时用 opencloud-sandbox-8.1.0/runopencloud.sh 再次拉起。确认体验后，按第十一章清理，再走方案 B 做正式部署。

五、方案 B：手动安装官方单二进制（生产推荐）

本章按生产布局手动安装：二进制进 /usr/local/bin、配置进 /etc/opencloud、数据进 /var/lib/opencloud、环境变量收敛为一个 env 文件、systemd 托管开机自启。这是 OpenCloud 官方 README 描述的形态（opencloud init && opencloud server）的完整工程化版本。

5.1 下载与校验

下载 8.1.0 单二进制（133 MB；直连慢时走代理，实测代理下载 9 秒完成）：

$ curl -fL -o opencloud-8.1.0-linux-amd64 https://github.com/opencloud-eu/opencloud/releases/download/v8.1.0/opencloud-8.1.0-linux-amd64
  0     0    0     0    0     0      0      0 --:--:-- --:--:--     0
100  133M  100  133M    0     0  13.5M      0  0:00:09  0:00:09 --:--:-- 17.1M
$ ls -l opencloud-8.1.0-linux-amd64
-rw-r--r-- 1 root root 139895928 Oct 22 03:49 opencloud-8.1.0-linux-amd64
$ sha256sum opencloud-8.1.0-linux-amd64
dcc57274dc9d66c02314f1bc45387bf41fd77a8662452c549adfb2e1a05783eb  opencloud-8.1.0-linux-amd64

安装到系统路径并验证版本：

$ install -m 755 /root/opencloud-8.1.0-linux-amd64 /usr/local/bin/opencloud

$ opencloud version
Version: 8.1.0
Edition: rolling
Compiled: 2026-10-05 00:00:00 +0000 UTC

💡 说明：Edition: rolling 表示这是跟随主干的滚动发布构建。OpenCloud 不依赖任何外部数据库或消息队列——README 原文："The OpenCloud backend does not use a database. It stores all data in the filesystem."（数据全部落文件系统）。

5.2 目录准备

$ mkdir -p /etc/opencloud /var/lib/opencloud

5.3 opencloud init 初始化

以环境变量指定生产布局（OC_CONFIG_DIR/OC_BASE_DATA_PATH）与管理员密码，执行 init：

$ export OC_CONFIG_DIR=/etc/opencloud/config \
    OC_BASE_DATA_PATH=/var/lib/opencloud \
    OC_URL=https://10.89.56.2:9200 \
    IDM_ADMIN_PASSWORD=q1w2e3r4
$ opencloud init --insecure yes --admin-password q1w2e3r4

实测回显（完整输出，共 5 行）：


=========================================
 generated OpenCloud Config
=========================================
 configpath : /etc/opencloud/config/opencloud.yaml

生成的配置文件共 131 行，ls 验证：

$ ls -la /etc/opencloud/config/
total 12
drwx------ 2 root root 4096 Oct 22 03:52 .
drwxr-xr-x 3 root root 4096 Oct 22 03:52 ..
-rw------- 1 root root 3836 Oct 22 03:52 opencloud.yaml

5.4 环境变量文件

init 只负责生成密钥类配置；运行期参数全部走环境变量。把变量收敛到 /etc/opencloud/opencloud.env（systemd 的 EnvironmentFile 加载，等价于逐个 export）：

$ cat > /etc/opencloud/opencloud.env <<'EOF'
# OpenCloud 全局基础
OC_CONFIG_DIR=/etc/opencloud/config
OC_BASE_DATA_PATH=/var/lib/opencloud
OC_URL=https://10.89.56.2:9200
OC_INSECURE=true
OC_LOG_LEVEL=info
# 入口 proxy
PROXY_TLS=true
# 管理员与演示数据
IDM_ADMIN_PASSWORD=q1w2e3r4
# 命令行验证用（生产可关闭）
PROXY_ENABLE_BASIC_AUTH=true
EOF

逐项说明（全部为 8.1.0 实测变量名，OC_* 为全局前缀）：

变量实测取值说明
OC_CONFIG_DIR/etc/opencloud/configopencloud.yaml 所在目录，需与 5.3 init 时一致（不一致会生成第二套配置）
OC_BASE_DATA_PATH/var/lib/opencloud数据根目录，启动后自动生成 idm/idp/nats/proxy/search/storage 子目录
OC_URLhttps://10.89.56.2:9200对外访问地址，必须 https:// 前缀（否则 idp 启动即 fatal，见第十章 Q2）
OC_INSECUREtrue允许自签证书的内网部署形态；生产配受信证书后改为 false
OC_LOG_LEVELinfo日志级别（debug/info/warn/error/fatal），详见配置参数详解篇
PROXY_TLStrueproxy 入口启用 TLS（9200 为 HTTPS）；false 时退化为明文 HTTP（实测见配置篇）
IDM_ADMIN_PASSWORDq1w2e3r4管理员密码，仅 idm 首次建库时生效（改密方法见第十章 Q4）
PROXY_ENABLE_BASIC_AUTHtrue允许 WebDAV/CLI 用账号密码直接认证，便于命令行验证；纯浏览器使用场景可关闭

5.5 systemd 托管

创建服务单元 /etc/systemd/system/opencloud.service：

$ cat > /etc/systemd/system/opencloud.service <<'EOF'
[Unit]
Description=OpenCloud file sharing platform
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
EnvironmentFile=/etc/opencloud/opencloud.env
ExecStart=/usr/local/bin/opencloud server
Restart=on-failure
RestartSec=5
TimeoutStopSec=90
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

⚠️ 注意：OpenCloud 主进程内部要拉起 40 余个微服务（supervised 模式），需要较高的文件描述符与优雅停机时间——LimitNOFILE=65536 与 TimeoutStopSec=90 是实测稳定运行的最小集，缺省值下重启可能出现端口释放慢导致 RestartSec 内启动失败。

启用并启动：

$ systemctl daemon-reload
$ systemctl enable opencloud
Created symlink /etc/systemd/system/multi-user.target.wants/opencloud.service → /etc/systemd/system/opencloud.service.
$ systemctl start opencloud
$ systemctl is-active opencloud
active

systemctl status 实测（启动后约 23 秒，内存占用 244.5 MB）：

$ systemctl status opencloud --no-pager -n 5 | head -10
● opencloud.service - OpenCloud file sharing platform
     Loaded: loaded (/etc/systemd/system/opencloud.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 03:52:22 UTC; 23s ago
   Main PID: 2766 (opencloud)
      Tasks: 25 (limit: 94371)
     Memory: 244.5M
        CPU: 1.781s
     CGroup: /system.slice/docker-8e6f83dd9084d03c7a0f5ee33fea922630d4a9478c00d1b385523e1be0775860.scope/system.slice/opencloud.service
             └─2766 /usr/local/bin/opencloud server

5.6 监听端口验证

$ ss -ltnp | grep 9200
LISTEN 0      4096               *:9200             *:*    users:(("opencloud",pid=2766,fd=190))

对外仅 9200 一个入口；其余内部服务监听在 127.0.0.1（ss -ltnp | grep opencloud 可见 127.0.0.1:9140/9154/9216/9250/9280 等数十个回环监听，均为 OpenCloud 进程，无需对外放行）。

数据目录在首次启动后自动生成六个子目录，验证：

$ ls /var/lib/opencloud/
idm  idp  nats  proxy  search  storage

💡 技术拓展：OpenCloud 的默认存储驱动是 decomposedfs——把每个文件/目录抽象为一个「节点」，元数据以二进制元信息文件落盘、文件内容单独存放，从而摆脱关系型数据库。同类文件同步系统的存储模型对比：Seafile 用 MySQL/MariaDB 存元数据 + 块存储去重；Nextcloud 用 PHP + 数据库存元数据；Syncthing 则完全对等无服务器。decomposedfs 的取舍是：单二进制零依赖、备份即拷目录，代价是海量小文件场景的元数据查询依赖内置索引（可通过 opencloud posixfs scan 重建）。本方案实际采用默认 decomposedfs。

六、方案对比与选择建议

维度方案 A：官方一键脚本方案 B：手动单二进制
命令量一条 curl 管道下载 + init + env + systemd，约 6 步
安装位置当前工作目录 sandbox 内/usr/local/bin + /etc/opencloud + /var/lib/opencloud
管理员密码固定 admininit 时自定（本文 q1w2e3r4）
演示用户自动创建（IDM_CREATE_DEMO_USERS=true）不创建
进程托管runopencloud.sh 前台运行，无自启systemd 托管，开机自启、崩溃自动拉起
日志终端输出journalctl -u opencloud 集中收集
适用场景一分钟体验/验证下载链路正式部署

选择建议：先用方案 A 验证网络与二进制可用性（尤其在国内网络环境验证下载链路），确认后按方案 B 正式部署；两方案共用同一套 OC_* 变量体系，从 A 迁移到 B 只需把 sandbox 的 config/data 指到新目录或重新 init。

七、配置说明

正式部署后日常会接触的三类配置位置与查看方法。

7.1 配置文件 opencloud.yaml

/etc/opencloud/config/opencloud.yaml（131 行）保存 init 时生成的密钥与内部服务凭据，关键字段实测如下（节选，密钥值已省略）：

token_manager:
  jwt_secret: <init 生成>
machine_auth_api_key: <init 生成>
system_user_id: 708e4596-d1d4-4f7f-9873-97eaa8a4dc5b
admin_user_id: b644ca39-58e7-4cdc-b3af-6693434e8826
idm:
  service_user_passwords:
    admin_password: q1w2e3r4
    idm_password: <init 生成>
    reva_password: <init 生成>
    idp_password: <init 生成>
proxy:
  insecure_backends: true
  • system_user_id/admin_user_id：管理员与服务账号的内部 UUID，init 一次性生成，勿改动；
  • idm.service_user_passwords：idm 内嵌 LDAP 中各服务账号的密码，供其他服务绑定 LDAP 使用；
  • proxy.insecure_backends：允许 proxy 以自签形态访问内部 HTTP 服务（配合 OC_INSECURE=true）。

⚠️ 注意：该文件权限为 600 且包含全部密钥，修改前先备份；其内容与 /var/lib/opencloud/idm 数据库强关联——只改 yaml 里的 admin_password 并不会改变实际登录密码（实测验证与结论见第十章 Q4）。

7.2 环境变量文件 opencloud.env

见 5.4 节表格。修改后需要 systemctl restart opencloud 生效；查看 systemd 实际加载的变量：

$ systemctl show opencloud --property=EnvironmentFiles
EnvironmentFiles=/etc/opencloud/opencloud.env (ignore_errors=no)

变量名速查（均为 8.1.0 实测存在的变量，完整逐项实测见本专栏配置参数详解篇）：全局 OC_URL/OC_INSECURE/OC_LOG_LEVEL/OC_LOG_PRETTY/OC_CONFIG_DIR/OC_BASE_DATA_PATH；入口 PROXY_TLS/PROXY_HTTP_ADDR；身份 IDM_ADMIN_PASSWORD/IDM_CREATE_DEMO_USERS。

7.3 日志查看

systemd 托管后日志统一进 journal：

$ journalctl -u opencloud -n 2 --no-pager
Oct 22 03:52:24 opencloud opencloud[2766]: {"level":"info","service":"frontend","host.name":"opencloud","pkg":"rhttp","time":"2026-10-22T03:52:24Z","line":"github.com/opencloud-eu/reva/v2@v2.51.0/pkg/rhttp/rhttp.go:278","message":"unprotected URL: /apps/files"}
Oct 22 03:52:24 opencloud opencloud[2766]: {"level":"warn","service":"frontend","host.name":"opencloud","pkg":"rhttp","traceid":"5174274ea4c60d7a69cca0e4cb43a203","host":"127.0.0.1","method":"GET","uri":"/","url":"/","proto":"HTTP/1.1","status":401,"size":0,"start":"22/Oct/2026:03:52:24 +0000","end":"22/Oct/2026:03:52:24 +0000","time_ns":10814,"time":"2026-10-22T03:52:24Z","line":"github.com/opencloud-eu/reva/v2@v2.51.0/internal/http/interceptors/log/log.go:112","message":"http"}

日志为 JSON 行格式（level/service/message 字段），排查启动问题时 grep fatal 直达根因。需要更易读的控制台格式可加 OC_LOG_PRETTY=true。

八、Web 登录与上传下载验证

部署完成后做端到端验证：Web 登录页可达、管理员凭据有效、文件上传/列表/下载闭环。

8.1 Web 入口与登录

浏览器打开 https://10.89.56.2:9200，出现证书告警（服务端使用自签证书，实测证书信息）：

$ echo | openssl s_client -connect localhost:9200 2>/dev/null | openssl x509 -noout -subject -issuer -dates
subject=O = Acme Corp, CN = OpenCloud
issuer=O = Acme Corp, CN = OpenCloud
notBefore=Oct 22 03:52:22 2026 GMT
notAfter=Oct 22 03:52:22 2027 GMT

自签证书 CN 为 OpenCloud、有效期一年、首次启动时自动生成——浏览器"高级 → 接受风险并继续"即可（生产环境为域名配受信证书后告警消失）。点击后进入登录页，页面标题实测为 Sign in - OpenCloud（OIDC 登录页，由内嵌 idp 服务提供）：

$ curl -sk "https://localhost:9200/signin/v1/identifier?client_id=web" | grep -oE "<title>[^<]*</title>"
<title>Sign in - OpenCloud</title>

输入 admin / q1w2e3r4 登录。凭据由内嵌 idp（LibreGraph Connect）校验，服务端侧等价验证（OCS whoami 接口返回当前用户身份）：

$ curl -sk -u admin:q1w2e3r4 https://localhost:9200/ocs/v1.php/cloud/user?format=json
{"ocs":{"meta":{"status":"ok","statuscode":100,"message":"OK"},"data":{"id":"admin","display-name":"Admin","email":"admin@example.org","user-type":"primary"}}}

首页 HTML 亦可直接确认 Web 应用就绪（SPA 入口与内置应用清单）：

$ curl -sk https://localhost:9200/ | grep -oE "<title>[^<]*</title>"
<title>OpenCloud</title>

8.2 上传下载闭环（WebDAV）

以下三步用 WebDAV 协议验证与 Web 端同一套存储链路（PROXY_ENABLE_BASIC_AUTH=true 时支持账号密码直连）：

① 上传（PUT，新文件返回 201）：

$ printf "Hello OpenCloud 8.1.0!\nWeb upload/download closed-loop verification.\n" > /tmp/hello-opencloud.txt
$ curl -sk -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" -X PUT \
    -T /tmp/hello-opencloud.txt \
    https://localhost:9200/remote.php/dav/files/admin/hello-opencloud.txt
201

② 列表（PROPFIND，返回 207 多状态）：

$ curl -sk -u admin:q1w2e3r4 -X PROPFIND -H "Depth: 1" \
    https://localhost:9200/remote.php/dav/files/admin/ | grep -o "<d:href>[^<]*</d:href>"
<d:href>/remote.php/dav/files/admin/</d:href>
<d:href>/remote.php/dav/files/admin/hello-opencloud.txt</d:href>
<d:href>/remote.php/dav/files/admin/Shares/</d:href>

③ 下载（GET）与校验：

$ curl -sk -u admin:q1w2e3r4 \
    https://localhost:9200/remote.php/dav/files/admin/hello-opencloud.txt
Hello OpenCloud 8.1.0!
Web upload/download closed-loop verification.

$ md5sum /tmp/hello-opencloud.txt
4f75d14bcf9a68d4d4a6540c79cc4391  /tmp/hello-opencloud.txt

下载内容与原文件逐字节一致，md5 相同（4f75d14bcf9a68d4d4a6540c79cc4391）——上传、列表、下载、Web 可见四点闭环验证通过。同一文件重复 PUT 覆盖时实测返回 204（No Content），属正常行为。

九、升级与多版本管理

OpenCloud 升级即"替换二进制 + 重启"，数据目录无需迁移（新版本启动时自动处理内部结构）。推荐用"多版本并存 + 软链切换"的方式管理，可随时回退。

9.1 多版本并存与软链切换

把不同版本的二进制以带版本号的文件名并存安装，/usr/local/bin/opencloud 作为软链指向当前使用版本：

$ install -m 755 /root/opencloud-8.1.0-linux-amd64 /usr/local/bin/opencloud-8.1.0
$ ln -sf /usr/local/bin/opencloud-8.1.0 /usr/local/bin/opencloud

升级到新版本（以未来发布 x.y.z 为例，版本号以 Releases 页实查为准）：

$ curl -fL -o /root/opencloud-x.y.z-linux-amd64 \
    https://github.com/opencloud-eu/opencloud/releases/download/vx.y.z/opencloud-x.y.z-linux-amd64
$ install -m 755 /root/opencloud-x.y.z-linux-amd64 /usr/local/bin/opencloud-x.y.z
$ systemctl stop opencloud
$ ln -sf /usr/local/bin/opencloud-x.y.z /usr/local/bin/opencloud
$ systemctl start opencloud
$ opencloud version

验证要点：opencloud version 应显示新版本号；systemctl is-active opencloud 为 active；journalctl -u opencloud -n 50 --no-pager | grep -i fatal 无 fatal 行；WebDAV 上传下载回归一遍。

9.2 升级前备份与回退

升级前先备份配置与数据（decomposedfs 布局，直接拷目录即可）：

$ tar -czf /root/opencloud-backup-$(date +%F).tar.gz /etc/opencloud /var/lib/opencloud

回退 = 软链切回旧版本 + 重启（ln -sf /usr/local/bin/opencloud-8.1.0 /usr/local/bin/opencloud && systemctl restart opencloud）。跨多个大版本回退时，存储与索引的内部结构可能已由新版整理，建议直接恢复备份的数据目录而不是原地回退。

⚠️ 注意：替换二进制前务必 systemctl stop opencloud——运行中替换文件会导致正在执行的进程行为不可预期；本机实测曾因软链切换时未停服造成 ExecStart 目标悬空（systemctl status 显示 code=exited, status=203/EXEC 一类失败），重新 install 真实文件后恢复。

十、常见问题与排障实录

Q1：浏览器打开 9200 端口提示证书不受信？

自签证书的预期行为（证书信息实测见 8.1 节：CN=OpenCloud、自签发、有效期一年）。内网试用直接"接受风险并继续"；服务端首次启动日志中会出现对应的证书生成告警（实测照抄）：

Oct 22 04:13:18 opencloud opencloud[3957]: {"level":"warn","service":"proxy","time":"2026-10-22T04:13:18Z","line":"github.com/opencloud-eu/opencloud/services/proxy/pkg/server/http/server.go:21","message":"No tls certificate provided, using a generated one"}

生产方案：为 OC_URL 的域名配置受信证书，之后将 OC_INSECURE 改为 false（实测 false 后服务正常运行，内部服务间凭生成的自签证书互信）。

Q2：把 OC_URL 配成 http:// 后服务起不来？

实测现象：OC_URL=http://10.89.56.2:9200 时 systemctl is-active 一直 activating（auto-restart），journal 可见 storage-users 反复重连 NATS 的 error；前台运行捕获到根因 fatal（实测照抄）：

{"level":"fatal","service":"idp","error":"invalid iss value, URL must start with https://","time":"2026-10-22T04:08:51Z","line":"github.com/opencloud-eu/opencloud/services/idp/pkg/service/v0/service.go:122","message":"could not bootstrap idp"}

原因：内嵌 OIDC 身份服务（idp）强制 issuer 为 https://。解决：OC_URL 一律使用 https:// 开头（自签证书场景配合 OC_INSECURE=true），改回后重启正常。

Q3：一键脚本跑起来没有任何输出就退出了？

实测现象：直接 bash install.sh 静默退出，script_run.log 为 0 字节、沙盒目录都没创建。定位：脚本第一行 set -euo pipefail，第 42 行 get_latest_version 调 GitHub API releases/latest；当走代理访问 GitHub API 被限流时（本环境代理出口 IP 实测返回），grep '"tag_name"' 匹配不到 → 管道非零 → pipefail 在任何 echo 之前退出。限流时的 API 实际返回（实测照抄）：

{"message":"API rate limit exceeded for 15.152.113.97. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)","documentation_url":"https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"}

解决：让 API 请求走直连、大文件下载走代理——export http_proxy=<代理> https_proxy=<代理> 的同时 export no_proxy=api.github.com；或者干脆手动下载二进制走方案 B。

Q4：修改 IDM_ADMIN_PASSWORD 或 opencloud.yaml 后 admin 密码没变？

实测现象：把 env 里的 IDM_ADMIN_PASSWORD 换成新值并重启 → 旧密码依然 207 可用、新密码 401；改 /etc/opencloud/config/opencloud.yaml 中 idm.service_user_passwords.admin_password 再重启 → 同样无效；Graph API 的 POST /graph/v1.0/users/admin/changePassword 实测 404（未提供该端点）。原因：该变量只作用于 idm 服务首次初始化数据库 时，密码随后固化在 /var/lib/opencloud/idm 的内嵌 LDAP 库中。实测验证：停服 → 把 idm 目录移走 → 带新密码重启 → 新密码 207、旧密码 401，证明密码随库固化。可行改密路径：Web 端设置里改密，或重建 idm 数据目录（⚠️ 会连带清空全部本地用户与组——实测组数据同样随 idm 库重建而消失，删除旧组返回 404——务必先备份）。

Q5：直接敲 opencloud --help 报 NATS 连接失败？

实测现象：

$ opencloud --help
Version: 8.1.0
Edition: rolling
Compiled: 2026-10-05 00:00:00 +0000 UTC

could not list services: Failed to connect to NATS Server: nats: no servers available for connection

原因：不带子命令的 --help 会尝试连接运行时（NATS 总线）枚举服务。服务运行时该命令可用；服务未启动时改用 opencloud help（实测可正常输出主命令树）或 opencloud <子命令> --help。

Q6：把 proxy 入口端口从 9200 改到 9210 就启动失败？

实测现象：PROXY_HTTP_ADDR=0.0.0.0:9210 时服务 activating 循环。前台捕获到 proxy 服务 panic（节选，实测照抄）：

{"level":"fatal","service":"opencloud","event":"opencloud: Failed service 'proxy' (5.999235 failures of 5.000000), restarting: false, panic: config: Cannot set options after data has been loaded, ...","service":"proxy","supervisor":"opencloud",...,"message":"service panic"}

同时 OC_URL 与 PROXY_HTTP_ADDR 同步改成 9210 后，换成另一个 fatal：Failed service 'userlog' ... error: listen tcp 127.0.0.1:9210: bind: address already in use——OpenCloud 内部服务默认占用 127.0.0.1 的 9210 起连续端口段（实测 ss -ltnp 可见 userlog 等绑定 9210）。解决：保持 9200 入口；确需改端口时必须整体重排全部服务端口变量（成本高、收益小，不建议）。

十一、卸载与清理

完全卸载按"停服务 → 删自启 → 删文件"三步（每步一条命令，逐条执行）：

$ systemctl stop opencloud
$ systemctl disable opencloud
Removed "/etc/systemd/system/multi-user.target.wants/opencloud.service".
$ rm -f /etc/systemd/system/opencloud.service
$ systemctl daemon-reload
$ rm -f /usr/local/bin/opencloud
$ rm -rf /etc/opencloud /var/lib/opencloud
$ rm -rf ~/opencloud-sandbox-* ~/opencloud-*-linux-amd64 ~/install.sh

仅保留数据、临时下线服务时，只执行前两步即可（disable 后不再开机自启，数据与配置原地保留，重新 enable + start 可恢复）。

十二、参考链接