Olares CLI 文件权限管理：`olares-cli files chown` 读取与修改 POSIX 属主 UID 完全指南

• 云原生
• 后端
• 运维

本指南以 Terminus 仓库中olares-files技能包的files chown命令为对象，讲解如何通过olares-cli读取（GET）与修改（PUT）Olares 个人云中文件/目录的 POSIX 属主 UID。你将掌握该命令的三种工作形态（查看、单点修改、递归修改）、支持与拒绝的命名空间边界、0（Root）与1000（User）两套 LarePass 预设值的安全含义，以及在实际 Agent 自动化场景中的安全操作纪律与常见报错处理。无论你是在为 LarePass Web 应用编写等价 CLI 操作脚本，还是需要把某个目录树"交还"给默认用户，本文给出的命令与源码级原理都直接可复用。

命令概览：文件属主的 Get / Set 语义

olares-cli files chown用于获取或设置远端文件/目录的 POSIX 属主 UID（owner UID）。它是 LarePass Web 应用文件属性对话框（"Permission" 权限标签页）的 CLI 对等实现——该对话框只暴露一个可写字段（属主 UID），因此 CLI 用单个动词覆盖了同一块功能面。

命令的三种形态由是否携带--uid决定（见 chown.go 中的Use定义）：

对应的底层 HTTP 协议形态（与服务端/api/permission/...端点一致，参见 permission.go）：

GET /api/permission/<fileType>/<extend><subPath> → {uid: <int>} PUT /api/permission/<fileType>/<extend><subPath>?uid=<int>[&recursive=1]

值得注意的实现细节是：--uid在 Cobra 层被定义为字符串类型而非整数（见 chown.go）。这样做的目的是把"用户没传--uid"与"用户传了--uid 0"两种情况严格区分开——前者触发 GET，后者即使值为 0 也触发 PUT。测试用例 TestNewChownCommand_FlagWiring 专门锁定了这一 flag 语义（uidFlag.Value.Type() != "string"即视为回归）。

另一个隐蔽但实用的细节：-R（--recursive-bsd）是-r的隐藏别名，在PreRunE中转换为recursive（见 chown.go），照顾习惯 BSD 风格-R的用户。

前置条件与配套阅读

使用本命令前需要满足：

• olares-cli已安装并位于PATH，且已激活 Olares profile（登录状态）。profile 管理见 olares-shared/SKILL.md：olares-cli profile list/profile login/profile use等。
• 建议先阅读技能包共享入口 olares-files/SKILL.md，了解olares-files技能套件的路由规则、活跃 profile 选择与鉴权 proceed/stop 门控。
• 理解 Olares 路径语法：每个资源形如<fileType>/<extend>/<subPath...>，fileType是存储类别，extend是卷/仓库/账号名，subPath是内部路径且前置/隐含。详细语法与各动词命名空间支持矩阵见 olares-files-paths.md。
• 需要查看每个子命令的完整参数时运行olares-cli files chown --help。

UID 约定：LarePass 的两套预设

LarePass 图形界面只向用户暴露两个预设值，CLI 完全对齐：

CLI接受任意非负整数，并不把--uid限制在这两个值上——协议本身接受任何整数，一个配置良好的 Olares 节点完全可以承载 LarePass 默认0 / 1000之外的 POSIX 用户。这两个值只是 GUI 呈现的选项（源码见 chown.go 的commonChownUIDPresets，其注释直接引用了前端 InfoDialog.vue 中permissionOption = [{label: 'Root', value: 0}, {label: 'User', value: 1000}]）。

命令输出时会为预设值追加人类可读标注：

drive/Home/Documents/foo.pdf uid=0 (Root) drive/Home/Pictures/Trip2024/ uid=1000 (User)

非预设值（如 42）不追加标注。该逻辑由prettifyUID实现（见 chown.go），并有 TestPrettifyUID 用例锁定：0 → " (Root)"、1000 → " (User)"、42 → ""。

UID 参数校验规则（parseChownUID，见 chown.go）：

• 空字符串 → 报错并提示--uid is empty; pass an integer；
• 非整数（如user、1k）→ 报错并提示 LarePass 预设值作为回退；
• 负整数一律拒绝（--uid must be non-negative）——原因在于服务端会把值 cast 成 uint，-1会被静默变成巨大 UID，因此必须在客户端大声失败。

以上校验均有对应测试锁定，见 TestParseChownUID。

命名空间边界：允许列表与拒绝原因

files chown只接受四个命名空间（对应前端permissionInDriveType中 Drive / Data / Cache 三类的展开，见 chown.go）：

drive/Common的版本门控并非空谈：在 common_gate.go 中，commonNamespaceMinOlaresVersion = "1.12.6"，requireCommonBackendVersion采用 fail-closed 策略——后端版本可检测且 >= 1.12.6 才放行；版本更旧或无法检测（离线/无缓存）时都直接拒绝并给出升级或改用drive/Home/drive/Data的提示（见 common_gate.go）。chown.go的runChown在解析路径后立即调用该门控（chown.go），与ls/rm/cp等其他动词共用同一套机制。

被拒绝的命名空间（客户端 fail-fast，不发出请求）：

每种拒绝都附带针对性的恢复提示（chownNamespaceError，见 chown.go）：sync 提示files repos、external 提示 GUI 行为、云账号提示 "object stores have no POSIX uid"。SupportedFileTypes在 permission.go 中定义，仅含drive与cache两项。测试 TestFrontendPathToChownTarget 逐一覆盖了允许路径的解析（含cache/node-a/scratch/build/深层路径）与全部拒绝分支（sync / external / 四种云 / 三类卷根）。

安全约束：什么时候该三思而后行

files chown的安全模型围绕"影响面"设计：

1. --uid是破坏性操作——必须先与用户确认意图。UID 改变会影响每一个读取该目录的应用（例如容器内以固定 uid 运行的 App 可能瞬间失去读写权限）。
2. 卷根一律拒绝：drive/Home/、drive/Data/、drive/Common/、cache/<node>/都不能作为目标——对整个命名空间根做 chown 的爆炸半径太大，几乎不可能是用户本意。若确实要整体展开，请选择深一层的子路径并配合-r。该校验在frontendPathToChownTarget中实现：strings.Trim(fp.SubPath, "/") == ""时直接报refusing to chown the root of <fileType>/<extend>; pick a child path（chown.go）。
3. -r会递归：所有后代条目都会被赋予新 uid。执行前务必先用olares-cli files ls确认目录内容，评估影响范围。

还有一个防止"静默 no-op"的细节：如果在没有--uid的情况下传了-r，命令会直接报错（--recursive only applies when setting a uid; pass --uid <int> to use it, or drop --recursive to GET the current uid，见 chown.go）——因为递归只对写操作有意义，这样设计能防止脚本本意是 PUT 却因漏传--uid而退化成 GET。

另外值得注意：drive/Home/第一层有十一个系统托管保留目录名，rename/rm/mv会拒绝以它们为源（见 olares-files/SKILL.md），但chown不受该保护影响；从实现看，chown的守卫是命名空间 + 卷根两级，嵌套内容可正常操作。

实战示例

以下示例均来自命令的 Long help（chown.go），可直接复制运行：

# 1. 只读检查：打印当前属主 olares-cli files chown drive/Home/Documents/foo.pdf # 2. 把单个文件交给 root olares-cli files chown drive/Home/Documents/foo.pdf --uid 0 # 3. 把整个目录树交给默认用户（递归） olares-cli files chown drive/Home/Pictures/Trip2024/ --uid 1000 -r # 4. Cache 命名空间（注意 <node> 需替换为真实节点名） olares-cli files chown cache/<node>/scratch/build/ --uid 1000 -r

建议工作流（来自文档的 Agent notes 与runChown实现）：

• PUT 前先 GET：GET 形态开销极低，且runChown在写操作前会先打印set uid → uid=N的意图行（见 chown.go），方便向用户展示当前值并确认变更。这也是文档明确推荐的纪律：任何 PUT 之前先展示当前 uid 并确认。
• -r失败后不要盲目重试：递归过程中的部分失败行为由服务端决定——出错时服务端可能已经改掉了一部分后代。此时应改为对几个抽样路径重新执行 GET 形态，确认实际落到哪些路径上，再决定下一步。

错误排查：常见报错与修复路径

401/403/404 的友好化处理集中在reformatChownHTTPErr（chown.go）：401/403 分支会建议重新登录（profile login，若知道 Olares ID 则直接带上--olares-id），404 分支回显chown <verb> <path>: not found。其他 4xx/5xx 原样透传HTTPError，其中已包含服务端响应体与请求 URL，是最有用的诊断信息。需要注意的是，permission.HTTPError与 share/rename 包中的错误类型同构（见 permission.go），错误体超过 500 字符会被截断，避免大响应污染终端。

与 LarePass Web 应用的对应关系

理解files chown的最佳方式是对照它的 GUI 孪生：

• 前端入口：LarePass 文件属性对话框的 "Permission" 标签页（InfoDialog.vue）——一个q-select下拉框提供Root(0)/User(1000)两个选项，外加一个 "recursive" 开关；该标签页只在 Drive / Data / Cache 三类下显示（permissionInDriveType）。
• Store 层：提交处理调用operationStore.getPermission/setPermission（operation.ts），拼出?uid=<uid>与&recursive=1查询参数（注意 GUI 发送的是字面"1"而非"true"，CLI 的permission.Client.Set按字节对齐了这一行为，见 permission.go），随后对dataAPIs().getDiskPath(file, 'permission')得到的路径发起 GET/PUT。
• Wire 层：/api/permission/...端点在 Web 端与resources、paste、raw、md5、repos等同属commonUrlPrefix系列（permission.go 的包注释）。该端点没有{code, message, data}信封：GET 返回扁平{uid}，PUT 返回小型状态对象；permission.Client只解码uid字段，未来服务端增加gid/mode等字段也不会破坏解析（permission.go）。
• URL 构建：路径逐段做百分号编码（encodepath.EncodeURL，与 share/cp/rm/upload 共用同一encodeUrl辅助函数），并统一补尾部/，保证与 GUI 字节一致（permission.go）。

给 Agent 的自动化纪律小结

• 把files chown当作影响面操作对待：PUT 前先 GET 展示当前 uid，-r前先files ls确认目录内容。
• 递归失败后不要盲目重试——改用 GET 抽样确认已生效路径。
• 若目标在sync/、external/或云账号下，换工具而不是硬试：files repos（sync ACL）或 LarePass GUI（external）。
• 版本敏感：涉及drive/Common时先确认后端 Olares >= 1.12.6；若无法确认后端版本，命令会 fail-closed 拒绝，属预期行为而非网络故障。

• 云原生
• 后端
• 运维