OkFile · PowerShell 高级指南

正在检查当前实例能力…

角色与权限

多人协作与自动化任务再选择队列角色。普通文件上传、下载和加密分享可直接使用基础命令。

身份	允许的操作
创建者 / 队列 admin	管理本队列、凭据和文件；查看与下载；不管理他人队列。
producer	投递文件、恢复或取消自己的上传；不能列出或下载文件。
consumer · shared	查看与下载所有未过期文件，独立确认处理。
consumer · work	查看列表、领取任务；凭有效租约下载、续租、释放或确认。

队列文件默认私有，所有下载、预览、raw、HEAD 与 Range 入口都验证队列权限。队列凭据、领取 receipt 和解密密钥分别保管，均不放进 URL。

01 · 安装与准备

所有场景共用这个 PowerShell 窗口。将已有 API Key 放进环境变量；有有效 API Key 的用户可以自行创建队列。准备命令将当前实例保存为默认服务地址，每次测试使用新的目录与队列名称。

python -m pip install --upgrade --index-url https://pypi.org/simple okfile==2.15.5
python -m okfile_cli upgrade
$env:Path = "$env:LOCALAPPDATA\okfile\cli\bin;$env:Path"
$env:OKFILE_SERVER = "https://hk.okfile.com"
$env:OKFILE_API_KEY = "替换为你已有的 API Key"
okfile config --server $env:OKFILE_SERVER
$run = Get-Date -Format "yyyyMMdd-HHmmss"
New-Item -ItemType Directory -Force "okfile-demo-$run" | Out-Null
Set-Location "okfile-demo-$run"
"Hello OkFile" | Set-Content -Encoding utf8 .\report.txt
okfile --version
okfile upload -h
okfile queue -h

预期：版本为 2.15.5。API Key 由实例管理员分发；队列管理权限只覆盖自己创建的队列。

02 · 普通文件上传与下载

普通文件默认生成可访问链接；私有交接请使用队列或下载密码。

$file = okfile upload .\report.txt --json | ConvertFrom-Json
okfile status $file.id
okfile download $file.downloadUrl -o .\received.txt
Get-FileHash .\report.txt
Get-FileHash .\received.txt

预期：两份文件的 SHA256 一致。重复下载到已有路径会拒绝覆盖，需明确加 --force。

03 · 带密码的分享链接

下载密码用于访问控制；需要服务器不能读取原文时，使用第 11 节的端到端加密。

$file = okfile upload .\report.txt --password --json | ConvertFrom-Json
# 上传时可见输入；收件人打开 downloadUrl 会看到密码输入页
$file.downloadUrl
okfile download $file.downloadUrl --password -o .\password-received.txt
# 自动化可使用环境变量，避免密码进入命令参数
$env:SHARE_PASSWORD = "替换为分享密码"
okfile upload .\report.txt --password-env SHARE_PASSWORD

预期：未验证时 /d、/i、/raw 和 HEAD/Range 均被拒绝。密码错误不会消耗下载次数。

04 · 上传续传、checksum 与取消

用自己的大文件替换路径。Ctrl+C 会保留上传状态，临时网络错误自动重试。

okfile upload .\large.mp4 --checksum sha256
# 中断后执行同一命令；或明确恢复
okfile upload .\large.mp4 --resume --checksum sha256
# 顺序字节续传
okfile upload .\large.mp4 --mode sequential --chunk-size 8388608
# 取消尚未完成的任务
okfile cancel .\large.mp4
# 丢弃旧任务并重建
okfile upload .\large.mp4 --restart

预期：恢复复用任务 ID，只补传缺失部分；原文件变化会拒绝显式 --resume。--restart 会取消旧任务。

05 · 下载中断与恢复

使用同一个 URL 和保存路径重新执行即可续传，客户端先核对 ETag、大小和任务身份。

okfile download FILE_URL -o .\large-received.mp4
# 下载中 Ctrl+C，然后再次执行同一命令
okfile download FILE_URL -o .\large-received.mp4 --retries 5 --retry-delay 2
# 远端身份变化时明确重新下载
okfile download FILE_URL -o .\large-received.mp4 --restart
# 已存在完整目标时，明确允许替换
okfile download FILE_URL -o .\large-received.mp4 --force

预期：中断保留 .okfile.part 和 .okfile.download.json；成功后移除临时文件。服务端有效期、下载次数和阅后即焚限制仍生效。

06 · 自行创建 shared 队列并签发凭据

创建队列与两把凭据在同一事务内提交。原 API Key 保留队列管理权；凭据文件包含秘密，请单独交付给对应成员。

okfile queue create "videos-$run" --mode shared --retention 7d --producer camera-01 --consumer editor-01 --credentials-out .\videos.keys.json
$shared = Get-Content -Raw .\videos.keys.json | ConvertFrom-Json
$shared.queue.id
okfile queue list
okfile queue info $shared.queue.id
# 也可自行设置长随机密钥（每把 32–256 字节且不含空白）
# $env:PRODUCER_SECRET / $env:CONSUMER_SECRET 应事先安全配置
# okfile queue create "custom-$run" --producer-key-env PRODUCER_SECRET --consumer-key-env CONSUMER_SECRET --credentials-out .\custom.keys.json

预期：凭据写入受限权限文件，终端不重复显示密钥。创建同名队列或覆盖现有凭据文件会被拒绝。

07 · shared：投递、列出、下载、确认

生产者只能投递，消费者可以查看、下载和确认；下载完成不自动等于业务处理完成。

$item = okfile upload .\report.txt --queue $shared.queue.id --key $shared.producer.key --json | ConvertFrom-Json
okfile queue files $shared.queue.id --key $shared.consumer.key
okfile download $item.id --queue $shared.queue.id --key $shared.consumer.key -o .\shared-received.txt
okfile queue ack $shared.queue.id $item.id --key $shared.consumer.key
okfile queue files $shared.queue.id --status acked --key $shared.consumer.key

预期：确认状态只属于当前消费者身份，文件保留到有效期；普通 URL 没有队列凭据不能下载。

08 · 多消费者与权限拒绝测试

每位消费者用独立凭据。共享同一把凭据会被视为同一个消费者；轮换密钥保留该身份。

okfile queue key create $shared.queue.id --role consumer --name editor-02 --credentials-out .\editor-02.json
$editor2 = Get-Content -Raw .\editor-02.json | ConvertFrom-Json
okfile queue files $shared.queue.id --status ready --key $editor2.key.key
# 以下操作预期失败：生产者无列表权限，匿名 URL 不可读
okfile queue files $shared.queue.id --key $shared.producer.key
curl.exe -I "$($item.downloadUrl)"
# 持有生产者凭据也不能创建新队列
okfile queue create forbidden --key $shared.producer.key

预期：editor-02 仍看到未确认项；越权列表返回 403，匿名文件请求返回 401，队列凭据不能创建系统级资源。

09 · work：领取、续租、释放、确认

一个文件同时只允许一个有效领取；领取凭据自动保存在本机，支持显式 --receipt 给其他进程使用。

okfile queue create "jobs-$run" --mode work --lease 30m --retention 7d --credentials-out .\jobs.keys.json
$work = Get-Content -Raw .\jobs.keys.json | ConvertFrom-Json
$job = okfile upload .\report.txt --queue $work.queue.id --key $work.producer.key --json | ConvertFrom-Json
$claim = okfile queue claim $work.queue.id --key $work.consumer.key --json | ConvertFrom-Json
okfile download $claim.item.id --queue $work.queue.id --key $work.consumer.key -o .\job-input.txt
okfile queue renew $work.queue.id $claim.item.id --key $work.consumer.key
# 处理失败时释放，其他消费者可立即领取
okfile queue release $work.queue.id $claim.item.id --key $work.consumer.key
# 再次领取，并在业务完成后确认
$claim = okfile queue claim $work.queue.id --file $job.id --key $work.consumer.key --json | ConvertFrom-Json
okfile queue ack $work.queue.id $claim.item.id --key $work.consumer.key

预期：没有任务时 JSON item=null；已领取项不能被第二次领取。租约到期后可重领，旧 receipt 无法确认新租约。ack 可安全重复。

10 · Agent 与跨机器处理

用 JSON 读取稳定字段。按文件 ID 做业务幂等；先可靠保存处理结果，再确认输入。

okfile upload .\report.txt --queue $work.queue.id --key $work.producer.key --json
$claim = okfile queue claim $work.queue.id --key $work.consumer.key --json | ConvertFrom-Json
if ($null -ne $claim.item) {
  # 在另一台机器上也可用领取得到的 receipt 下载或续租
  okfile download $claim.item.downloadUrl --queue $work.queue.id --key $work.consumer.key --receipt $claim.item.receipt -o .\agent-input.bin
  okfile queue renew $work.queue.id $claim.item.id --key $work.consumer.key --receipt $claim.item.receipt
  # 此处执行你的处理，并把结果上传到目标队列；成功后确认
  # okfile upload .\result.pdf --queue RESULT_QUEUE --key RESULT_PRODUCER_KEY --json
  okfile queue ack $work.queue.id $claim.item.id --key $work.consumer.key --receipt $claim.item.receipt
}

预期：队列提供至少一次交付，Agent 崩溃后任务不会永久丢失；重领可能重复处理，所以业务应幂等。不要在结果交付前 ack。

11 · 端到端密码加密

本机使用 scrypt 派生密钥与 AES-256-GCM 分块认证加密；密码至少 6 字符，原始文件名也加密。密码只通过单独提示输入。

okfile upload .\report.txt --encrypt-password
okfile download FILE_ID --decrypt-password -o .\decrypted.txt
Get-FileHash .\report.txt
Get-FileHash .\decrypted.txt
# 本地加密/解密，不经过服务器
okfile encrypt .\report.txt -o .\report.okenc
okfile decrypt .\report.okenc -o .\local-decrypted.txt

预期：收件方只需链接和相同密码，不需要密钥文件。错误密码、篡改和截断不会输出最终明文。密码丢失后无法恢复。脚本可用 --encrypt-password-env / --decrypt-password-env 从环境变量读取，不要在参数中填写密码值。

12 · 凭据轮换、撤销与恢复

管理操作使用创建队列时的原 API Key，或另行签发的该队列 admin 凭据。生产者、消费者密钥不能管理成员。

okfile queue key list $shared.queue.id
okfile queue key rotate $shared.queue.id $shared.consumer.id --credentials-out .\rotated.json
$rotated = Get-Content -Raw .\rotated.json | ConvertFrom-Json
$shared.consumer.key = $rotated.key
# 原密钥立即失效；消费者身份和 shared 确认记录保留
okfile queue files $shared.queue.id --key $rotated.key
okfile queue key revoke $shared.queue.id $shared.consumer.id
okfile queue key enable $shared.queue.id $shared.consumer.id

预期：轮换或撤销 work 消费者凭据时，其未完成租约释放。enable 恢复当前密钥，不会恢复轮换前的旧密钥。

13 · 配额、有效期与删除

容量统计包含准备中的文件，防止多个生产者并发超额占用。删除先停止访问，实体数据由周期清理回收。

okfile queue create "tiny-$run" --mode shared --max-bytes 8 --retention 1h --credentials-out .\tiny.keys.json
$tiny = Get-Content -Raw .\tiny.keys.json | ConvertFrom-Json
# report.txt 超过 8 字节，此命令预期失败且不发送文件数据
okfile upload .\report.txt --queue $tiny.queue.id --key $tiny.producer.key
okfile queue update $shared.queue.id --retention 14d
okfile queue delete-file $shared.queue.id $item.id
okfile queue delete $tiny.queue.id

预期：容量不足返回 QUEUE_QUOTA_EXCEEDED；修改保留期只影响以后新建的上传任务。非空队列不能切换模式。已删除队列不会把旧文件变成公开文件。

14 · 分页读取与精准操作

按稳定游标逐页读取，避免大队列一次返回过多记录；status 的 ready/acked 在 shared 中按当前消费者计算。

$page = okfile queue files $shared.queue.id --limit 20 --status ready --key $shared.consumer.key --json | ConvertFrom-Json
if ($page.nextCursor) {
  okfile queue files $shared.queue.id --limit 20 --status ready --after $page.nextCursor --key $shared.consumer.key --json
}
# work 可按文件 ID 领取；被别人持有时不会抢走
okfile queue claim $work.queue.id --file FILE_ID --key $work.consumer.key --json

预期：nextCursor 为空表示本次遍历结束；新文件可在下次从第一页扫描发现。

15 · 整个目录：发布静态站点

现有 publish 适用于 HTML、图片、脚本和资源构成的网站，保留目录路径。普通素材目录的批量清单上传是后续独立功能。

okfile publish .\my-site --name demo-site
# 修改文件后可复用发布状态恢复
okfile publish .\my-site --state-file .\site-state.json

预期：返回站点链接；这是站点发布，不应把密码或凭据文件放进公开站点目录。

16 · 测试清理、升级与诊断

前两条会关闭本次测试队列并使文件到期，需要保留时请跳过。托管启动器每天检查更新，当前传输保持原版本，下次启动切换。

# 只清理本次创建的测试队列；要保留测试文件时跳过这两条
okfile queue delete $shared.queue.id
okfile queue delete $work.queue.id
okfile upgrade --check
okfile upgrade
okfile upgrade --diagnose
okfile config set auto-update off
okfile config set auto-update on
# 新版本出现问题可离线回退，并关闭自动更新
# okfile upgrade --rollback

预期：diagnose 显示实际 Python、命令路径和托管版本。若裸 okfile 指向旧环境，按安装说明将固定启动器目录放在 PATH 前面。