使用命令管理服务器

SpaceBuilder 可执行文件（setfn-spacebuilder）除了启动服务器的功能外，还包含在终端中使用的管理命令。当无法登录管理员页面时，可用于恢复账户和访问限制，或查看端口、语言等设置。

本文档是面向安装和运营服务器的管理员的参考文档。日常管理请在管理员页面中进行，仅在无法使用管理员页面时才使用命令。

开始之前

在安装了 SpaceBuilder 的计算机终端中执行。
使用与运行 SpaceBuilder 相同的操作系统用户账户执行。默认配置路径位于该用户的主目录下；如果安装在了其他路径，则必须指定与运行中服务器相同的配置文件。
示例以可执行文件位于主目录（~/setfn-spacebuilder）的情况为准。如果放在了其他位置，请改为相应路径。
以 user、unblock、ip、admin、login、logout 开头的管理命令需要在服务器停止的状态下执行。

指定运行中服务器的配置路径

Linux 的默认配置文件是 ~/.config/SetFN/config.yaml。如果服务以其他账户或单独的配置路径运行，请确认服务启动命令中指定的路径。

使用 -c 或 --config 指定该配置文件。以下是以 /srv/setfn/config.yaml 运行的服务器示例。请改为实际的文件路径。

~/setfn-spacebuilder -c /srv/setfn/config.yaml port get
~/setfn-spacebuilder -c /srv/setfn/config.yaml user list

本文档中的其他管理命令也要加上同样的 -c 选项。如果是通过 -H 或 --home 指定路径运行的，该选项也要与运行命令保持一致。同时指定 -c 时，配置文件的选择以 -c 为准。

停止并重新启动服务器

管理用户、访问限制、设备连接的命令，以及 admin status、admin logout-all 等，会直接打开服务器的数据库。如果其他进程正在使用同一数据库，可能会在重试后以 Database is still locked 消息结束。admin reset-config 不会打开数据库，而是删除配置文件，但此操作也要在停止服务器后执行。

如果设置了自动启动，请按以下顺序执行。

sudo systemctl stop setfn-spacebuilder

执行所需命令后，重新启动服务器。

sudo systemctl start setfn-spacebuilder

如果是在终端中直接运行的，请在该终端中按 Ctrl+C 停止。

设置控制台访问密码

user 和 unblock 命令在执行时会询问 Console Access Password。此密码是在环境变量 SETFN_CONSOLE_PASSWORD 中设置的值。执行命令之前，请在同一终端中设置该值。

export SETFN_CONSOLE_PASSWORD="自行设置的密码"

此值仅用于本地控制台命令的访问确认，不是用于更改工作空间管理员密码或 SetFN 账户密码的设置。在 Console Access Password 处输入在此终端中指定的值。

命令一览

命令	作用	停止服务器
`serv`	启动服务器。不带命令直接运行可执行文件也会启动服务器。	-
`version`	显示版本和构建信息。	不需要
`lang get`、`lang set <代码>`、`lang list`	查看或更改终端消息语言。支持 `en`、`ko`、`ja`、`zh`。	不需要
`port get`	查看当前服务器端口及其是否被占用。	不需要
`homepath get`	查看存储数据的主路径。	不需要
`user list`	显示用户账户列表。	需要
`user add`、`user delete`	添加或删除用户账户。	需要
`user password`	更改用户的密码。	需要
`user promote`	更改用户的角色。	需要
`user mfa reset`	关闭管理员账户的两步验证（紧急恢复）。	需要
`unblock`	紧急恢复登录屏蔽。与 `user unblock` 相同。	需要
`ip status`、`ip add`、`ip remove`、`ip enable`、`ip disable`	管理 IP 访问限制和允许列表。	需要
`admin status`、`admin status-json`	查看服务器状态和设置。`status-json` 以 JSON 格式显示状态信息。	需要
`admin logout-all`	使所有用户退出登录。	需要
`admin reset-config`	删除配置文件，重新开始初始设置。	需要
`admin knowledge-backup`、`admin knowledge-restore`	备份或恢复知识存储。	需要
`admin vector-instance-id`、`admin prepare-clone`	将复制的服务器准备为可作为独立实例运营。请参阅迁移服务器。	需要
`login`、`logout`	在终端中将此设备注册到 SetFN 账户或解除注册。	需要

各命令的详细选项可在命令后加上 --help 查看。

~/setfn-spacebuilder user --help

无法登录时的恢复方法

以下命令均需在停止服务器并设置控制台访问密码后执行。

解除登录屏蔽

如果因反复登录失败导致管理员的访问被屏蔽，请将用于访问的计算机 IP 添加到安全白名单。

~/setfn-spacebuilder unblock --ip 203.0.113.10

使用以下命令查看当前的恢复状态。

~/setfn-spacebuilder unblock --status

如果添加 IP 后仍无法访问，请暂时关闭登录安全功能。

~/setfn-spacebuilder unblock --all

~/setfn-spacebuilder unblock --enable-security

确认目标用户账户

先查看现有 Workspace 用户账户列表。

~/setfn-spacebuilder user list

列表显示 ID、Username、Nick、Email 和 Active。在下面的命令中，请使用要恢复账户的登录 Username 替换整个 <用户账号>。Nick 是界面上显示的名称，不是 -u 所需的登录用户名。

修改管理员密码

~/setfn-spacebuilder user password -u "<用户账号>" --password "新密码"

-u 必须填写现有 Workspace 账户用于登录的 Username。请从 user list 中确认该值，并替换命令中的整个 <用户账号>。输入的命令会保留在终端历史记录中，因此建议登录后在管理员页面中再修改一次密码。新密码遵循服务器的密码规则，常用或已泄露的密码会被拒绝。新安装服务器的默认规则为至少 12 个字符。

关闭管理员两步验证

当管理员同时丢失了认证应用和恢复码而无法登录，且没有其他可在管理员页面中重置的最高管理员时使用。

~/setfn-spacebuilder user mfa reset "<用户账号>"

该账户的认证应用设置和恢复码会被删除，正在登录的会话全部结束。下次登录只验证密码；如果 要求管理员启用两步验证 策略已开启，登录后需要重新设置。执行记录会以 已重置两步验证 记入审计日志。对未使用两步验证的账户执行时，不会有任何更改，只显示提示。设置步骤请参阅设置管理员两步验证。

找回管理员权限

如果没有任何具有管理员权限的账户，请更改现有用户的角色。

~/setfn-spacebuilder user promote -u "<用户账号>" -r admin

这里，-u "<用户账号>" 指要恢复的实际 Workspace 账户，-r admin 中的 admin 是要授予的固定角色值。与此不同，admin status 中的 admin 是管理命令组，不是用户名或角色。

选项	说明
`-u`、`--username`	要更改角色的现有 Workspace 账户登录 `Username`。
`-r`、`--role`	`superuser`、`admin`、`user` 之一。未输入时为 `superuser`。

添加和删除用户账户

~/setfn-spacebuilder user add -u newadmin -n "新管理员" --admin

选项	说明
`-u`、`--username`	用于登录的用户名。
`-n`、`--nickname`	在界面上显示的名称。
`--password`	密码。未输入时，会在屏幕上显示自动生成的密码。
`--admin`	添加为管理员。

删除账户时需指定用户名。最后一位管理员无法删除。

~/setfn-spacebuilder user delete -u olduser

管理 IP 访问限制

开启 IP 访问限制后，只能从允许列表中的 IP 访问管理员页面。当允许列表设置错误导致无法访问管理员页面时，可使用命令修复。

查看当前状态和允许列表。

~/setfn-spacebuilder ip status

向允许列表添加或移除 IP 地址或 CIDR 范围。

~/setfn-spacebuilder ip add --ip 192.168.1.100
~/setfn-spacebuilder ip add --ip 192.168.1.0/24
~/setfn-spacebuilder ip remove --ip 192.168.1.100

开启或关闭访问限制。

~/setfn-spacebuilder ip enable
~/setfn-spacebuilder ip disable

查看服务器设置

~/setfn-spacebuilder port get
~/setfn-spacebuilder homepath get
~/setfn-spacebuilder lang get

终端消息语言可以像 lang set ko 这样直接更改。
port set <端口> 和 homepath set <路径> 不会更改值，而是告知应在配置文件中填写的内容；port set 还会同时显示该端口是否可用。修改配置文件后，需要重新启动服务器才会生效。
端口可使用 3000 到 65535。默认端口为 8510。

恢复 SetFN 账户的设备连接

此命令用于管理 SetFN 账户与服务器设备之间的连接。工作空间用户账户的登录屏蔽或密码，请使用前面的 user·unblock 命令恢复。

停止服务器，并使用与运行中服务器相同的配置路径开始连接。

~/setfn-spacebuilder login

按照终端中显示的认证引导，在浏览器中完成批准。要重新连接已注册的设备，请使用以下命令。

~/setfn-spacebuilder login --force

如果认证信息已过期或无效而需要重新连接，请先解除现有连接，再重新注册。

~/setfn-spacebuilder logout
~/setfn-spacebuilder login --force

logout 默认会清理本地站点令牌、设备密钥和认证文件。logout --unlink 是执行同样的完整解除操作的兼容选项。如果要保留设备密钥和认证文件、仅清理站点会话令牌，请使用 logout --keep-link。

重新连接完成后，重新启动服务器，并在管理员页面中确认许可证注册状态。

管理服务器状态与登录会话

查看服务器状态和当前设置。

~/setfn-spacebuilder admin status

如果怀疑账户信息泄露，请让所有用户退出登录。用户需要重新登录。

~/setfn-spacebuilder admin logout-all

知识存储的备份与恢复请参阅知识存储运维。

注意事项

Linux 只保留进程名的前 15 个字符，因此在 ps -e 或 top 中显示为 setfn-spacebuil。确认是否正在运行时，请使用 pgrep -f setfn-spacebuilder。
添加用户、管理屏蔽等可以在管理员页面中完成的操作，建议在管理员页面中进行。与账户和屏蔽相关的命令必须停止服务器才能执行。