• 后端
• 密码学

导读

本文是 Upspin 服务器部署指南 的 Ubuntu 分支实战教程，完整讲解如何在 Debian/Ubuntu Linux 服务器上创建运行upspinserver的专用系统账户、拷贝服务端二进制、配置 Let's Encrypt 证书缓存目录，并通过 systemd 将upspinserver注册为开机自启的常驻服务。读完本文你将掌握一套可复现的部署流程，包括如何用setcap让非 root 进程绑定 80/443 端口、如何用systemctl启停服务、以及如何用journalctl排查服务器日志；文章同时结合仓库源码解释每一步背后的实现原理，便于你排查部署过程中可能遇到的端口、权限与证书问题。

前置阅读：本文是 Setting up upspinserver 的组成部分，请先阅读该文档完成注册账号、域名配置与二进制构建等前置步骤，再继续本文的服务器端操作。

部署前提与环境说明

本文的部署步骤面向以下环境，开始之前请逐项确认：

• 你拥有一台可访问的 Debian 或 Ubuntu Linux 服务器，且服务器可以通过你选择的upspin.example.com主机名被公网访问；
• 你已经在工作站上按照 server_setup.md 的指引完成了 Upspin 账号注册、域名 DNS 配置，并针对所选存储后端构建好了upspinserver二进制；
• 服务器已部署 systemd 作为 init 系统（Ubuntu 16.04 及绝大多数现代 Debian/Ubuntu 发行版均满足）。

文档作者明确提示：这些步骤已在 Ubuntu 16.04 上验证通过，不同系统上的具体命令可能有所差异，例如包管理器、用户创建工具的语法或 systemd 单元文件的行为可能随发行版演进而变化。实际部署时请以当前系统的man手册与发行版文档为准。

本文沿用原文档的提示符约定：local$表示在工作站上执行的命令，server%表示以普通用户身份在服务器上执行，server#表示以 root 身份在服务器上执行。

二进制名称说明：根据 server_setup.md，针对不同存储后端构建出的二进制可能叫upspinserver，也可能带有云服务后缀（如upspinserver-gcp）。无论原始名称是什么，拷贝到服务器时统一安装为upspinserver，这样后续所有指令对所有配置变体保持一致。从源码结构看，upspinserver是一个合并的 DirServer 与 StoreServer：在 cmd/upspinserver/main.go 中，upspin.io/cloud/storage/disk被以匿名导入方式注册本地磁盘存储后端，随后调用upspinserver.Main()启动服务并交给cloud/https包监听 HTTPS；而 serverutil/upspinserver/main.go 中同时创建了store/server与dir/server两个生产实现实例，并挂载到/api/Store/与/api/Dir/两个 HTTP 路径。

第一步：在服务器上创建专用运行账户

upspinserver不应以 root 身份运行。作为系统服务，它为自身创建了一个专用 Unix 账户upspin，所有后续文件（二进制、Let's Encrypt 缓存、服务器数据）都围绕这个账户组织。

以下命令必须以超级用户root在服务器上执行（可通过sudo su进入 root shell）。

创建 Unix 账户

server# useradd -m upspin

-m选项同时创建用户主目录（通常为/home/upspin），该目录后续会用于存放二进制与缓存。在较新的 Ubuntu 上你也可以用adduser upspin（交互式）达到类似效果，但非交互的useradd更适合脚本化部署。

配置 SSH 访问（可选但推荐）

为方便后续运维，为upspin账户配置 SSH 公钥登录。先切换到该账户并准备~/.ssh：

server# su upspin server% cd $HOME server% mkdir .ssh server% chmod 0700 .ssh server% cat > .ssh/authorized_keys (Paste your SSH public key here and type Control-D and Enter) server% chmod 0600 .ssh/authorized_keys

注意两个权限位是关键：.ssh目录必须是0700，authorized_keys文件必须是0600，否则 OpenSSH 出于安全考虑会拒绝使用该公钥。此后你就能从工作站以ssh upspin@upspin.example.com登录服务器执行运维操作。

创建 Let's Encrypt 缓存目录

server% mkdir -p upspin/letsencrypt

即在/home/upspin/upspin/letsencrypt创建证书缓存目录。这个路径与源码中的默认值相呼应：在 flags/flags.go 中，Let's Encrypt 缓存目录的默认值为upspinDir("letsencrypt")，即$HOME/upspin/letsencrypt；注释同时要求该目录"仅属主可访问（chmod 0700）"，因为其中保存着可能敏感的证书与账户私钥材料。在 cloud/https/https.go 中，ListenAndServe检测到-letscache非空时，会以os.MkdirAll(dir, 0700)确保目录存在，并将该目录交给autocert.DirCache作为 Let's Encrypt 证书缓存。

第二步：将 upspinserver 二进制拷贝到服务器

前置的构建步骤（见 server_setup.md 的 "Set up storage and build the upspinserver binary" 小节）已在工作站上产出二进制。本文以 64 位 Linux 为例：

local$ GOOS=linux GOARCH=amd64 go build upspin.io/cmd/upspinserver

注意：cmd/upspinserver默认使用本地磁盘存储，数据存放在$HOME/upspin/storage（源码实现在 serverutil/upspinserver/main.go 中：未提供云存储配置时，使用"backend=Disk", "basePath=" + storagePath初始化 StoreServer）。若选择云端存储（GCP、Drive、AWS、Dropbox、B2），请改按 server_setup.md 中列出的对应分支指南构建带后缀的二进制。另外请知悉：把数据存在服务器本地磁盘意味着一旦磁盘损坏，所有 Upspin 数据将全部丢失。

在服务器上完成upspin账户与目录准备后，回到工作站，用scp将二进制推送到服务器并直接命名为upspinserver（把upspinserver-foo替换为你实际构建的二进制名）：

local$ scp upspinserver-foo upspin@upspin.example.com:upspinserver

拷贝完成后二进制位于/home/upspin/upspinserver，与下一步 systemd 单元文件中的ExecStart路径一一对应。

第三步：用 systemd 将 upspinserver 注册为系统服务

以下命令同样需以 root 身份在服务器上执行，并假定服务器运行 systemd。

创建 service 单元文件

创建文件/etc/systemd/system/upspinserver.service，内容如下：

[Unit] Description=Upspin server [Service] ExecStart=/home/upspin/upspinserver User=upspin Group=upspin Restart=on-failure [Install] WantedBy=multi-user.target

对单元文件关键字段的说明：

• ExecStart：启动命令，指向第二步拷贝到/home/upspin/upspinserver的二进制，省略参数即可使用全部默认值；
• User/Group：指定进程以upspin账户运行，避免以 root 运行服务带来的安全风险；
• Restart=on-failure：进程异常退出时由 systemd 自动重启，提升可用性；
• WantedBy=multi-user.target：将服务挂到多用户运行目标下，配合systemctl enable实现开机自启。

补充一个默认值细节：upspinserver不带任何参数启动时，flags/flags.go 中定义的默认监听地址为-https=:443（HTTPS）、-http=:80（HTTP），Let's Encrypt 缓存目录默认$HOME/upspin/letsencrypt，日志级别默认info。这意味着只要二进制与账户就绪，单元文件无需写任何参数即可正常工作。

允许非 root 进程监听 80 与 443 端口

upspinserver需要同时监听 80 和 443 端口，才能通过 HTTP-01 挑战从 Let's Encrypt 获取 TLS 证书——cloud/https/https.go 中，当启用 Let's Encrypt 时会额外在:80上启动一个 HTTP 服务器，用于应答证书挑战并把其余请求重定向到 HTTPS。

Linux 默认只允许 root 绑定 1024 以下端口，而我们希望进程以upspin用户运行。解决办法不是改用 root，而是用setcap为二进制单独授予绑定网络端口的 capability（以 root 执行）：

server# setcap cap_net_bind_service=+ep /home/upspin/upspinserver

其中+ep表示给二进制添加 effective 与 permitted 两个标志位，使该文件在执行时拥有绑定特权端口的权限。

重要提醒：每当upspinserver二进制被更新（重新拷贝替换文件）后，必须重新执行一次这条setcap命令，因为setcap附加在文件 inode 上的 capability 标记在文件被覆盖时会丢失。

启用并启动服务

server# systemctl enable --now /etc/systemd/system/upspinserver.service

enable建立开机自启的符号链接，--now立即启动服务（等价于enable+start两步）。日常运维命令：

server# systemctl stop upspinserver server# systemctl restart upspinserver

分别用于停止与重启服务。

查看服务日志

server# journalctl -f -u upspinserver

-f让journalctl持续跟随输出，-u upspinserver过滤出该服务单元的日志。这对部署调试极为重要，例如你可以在日志中看到本文稍后提到的启动模式提示信息，或排查证书申请失败、端口被占用等问题。

启动模式：理解 "setup mode" 与后续配置

部署完成后，upspinserver会进入所谓的"setup mode"（配置模式），等待工作站执行upspin setupserver完成正式配置。这一行为有明确的源码依据：在 serverutil/upspinserver/main.go 的Main()中，若服务器配置目录下不存在配置文件，会打印：

Configuration file not found. Running in setup mode.

并把根路径/挂载为setupHandler；cmd/upspin/setupserver.go 中的upspin setupserver命令会向https://<host>/setupserver发起 POST，把Writers、public.upspinkey、secret.upspinkey、serverconfig.json这四类配置（见 subcmd/server.go 的SetupServerFiles列表）推送给服务器，服务端在 serverutil/upspinserver/main.go 的setupHandler中校验并写入这些文件后，重新初始化服务并切换到正常服务模式。

因此完整的部署节奏是：

1. 按本文完成账户、二进制与 systemd 服务注册；
2. 回到 server_setup.md 继续执行其中的"Test connectivity"与"Configure upspinserver"小节，即在浏览器访问https://upspin.example.com/应看到Unconfigured Upspin Server字样；
3. 在工作站运行upspin setupserver -domain=example.com -host=upspin.example.com完成服务器用户注册、配置推送与用户根目录创建；
4. 最后用echo Hello, Upspin | upspin put you@gmail.com/hello与upspin get you@gmail.com/hello验证读写链路。

若配置出错需要重来，可删除服务器上的$HOME/upspin/server目录并重新执行upspin setupserver。注意该目录包含目录服务器数据，以及使用本地磁盘存储时的全部对象数据，删除即等于清空所有已写入的 Upspin 数据，务必谨慎。

部署检查清单

部署完成后，可用下表快速自查：

如果页面无法加载，优先查看journalctl日志：常见原因包括 Let's Encrypt 缓存目录权限不正确、setcap未在二进制更新后重跑、服务器防火墙未放行 80/443，以及 DNS A 记录尚未指向服务器 IP（DNS 解析是 Let's Encrypt 域名验证的前提之一）。

小结

本文完整覆盖了在 Ubuntu/Debian 服务器上运行upspinserver的全部服务器端步骤：创建专用upspin系统账户、配置 SSH 公钥与 Let's Encrypt 缓存目录、统一以upspinserver名称部署二进制、编写 systemd 单元文件实现开机自启与崩溃自动重启、用setcap安全地授予 80/443 端口绑定能力，以及用systemctl/journalctl完成日常管理与日志排查。文中同时对照 cmd/upspinserver/main.go、serverutil/upspinserver/main.go、cloud/https/https.go 与 flags/flags.go 等源码，说明了默认监听端口、Let's Encrypt 证书缓存机制与 setup mode 的底层实现，帮助你理解每一步部署操作的实际效果。服务启动并进入 setup mode 后，请继续回到 server_setup.md 完成upspin setupserver配置与端到端读写验证。

• 后端
• 密码学