FRP 使用指南（公开，无需登录）

管理台：https://manager.u.clock-p.com/
客户端下载：https://u.clock-p.com/
公开文档：https://manager.u.clock-p.com/howto
配置下载：https://manager.u.clock-p.com/frpc.toml

登录与账号
   可使用密码、Google 或 GitHub 登录。首次第三方登录后显示“待绑定账号”，
   需要管理员先创建实际账号，再在“身份管理”中选择该身份绑定已有账号。
   绑定后刷新即可进入账号并创建用户 Token；待绑定时不能使用业务功能。
   登录方式不决定服务归属，Cookie/Token 不包含可解码的身份或来源信息。
   已绑定的任意登录身份都可修改实际账号的默认密码，但必须输入旧密码。

1. 账号凭据目录（给用户和 LLM 的操作约定）
   Linux 根目录：~/.frp.clock-p.com/
   Windows 根目录：%APPDATA%\frp.clock-p.com\
   使用实际运行 frpc 的系统用户目录；不要误用管理员或其他用户的目录。

   目录结构：
   .frp.clock-p.com/
   ├── default.txt       内容是默认账号名，例如 alice，允许末尾换行
   ├── alice/
   │   └── token         只保存该账号的原始用户 Token
   └── bob/
       └── token

   用户明确指定账号时，LLM 直接选择该账号目录，不要求 default.txt 存在。
   未指定账号时，LLM 必须先查找并读取根目录中的 default.txt，去除首尾空白，
   再读取 <根目录>/<username>/token。default.txt 存在于根目录，不在账号目录。
   账号名必须为 2–32 位小写字母或数字，不得含路径分隔符、.. 或额外内容。
   如果 default.txt 缺失、为空、格式错误，或所选目录/token 缺失、为空，
   明确报告缺失项，不猜账号、不自动切换、不扫描其他 Token 试用。
   用户提供新的 Token 时，先通过下面的接口验证并取得 username，再创建该账号
   目录、写入 token，无需用户额外提供 username。不要尝试从随机 Token 中解码账号。
   若用户同时指定了账号，必须与接口返回值一致；不一致时报告，不静默换账号。
   首次设置可将已验证的 username 写入 default.txt。已有默认账号只在用户要求切换时修改。
   目录已存在时保留其他文件，不擅自覆盖已有 Token。

   文件名统一使用 token，不再使用 user-token.txt 或 feishu- 前缀。
   不另存 username / feishu-user_name 文件；后续其他凭据放在对应账号目录内。
   目录名只用于客户端选择凭据；真实身份和域名归属由服务端验证 Token 决定。
   不得把目录名填进 frpc 的 user 字段来声明身份。
   不将 Token 内容输出到聊天、日志或配置正文，只在配置里填写文件路径。
   Linux 根目录及账号目录权限设为 700，token 和 default.txt 文件设为 600。
   Windows 将凭据文件访问权限限制为运行客户端的用户。
   不读取其他站点旧目录中的凭据，也不读取 feishu-* 文件。
   此凭据目录供接入同一账号中心的站点共用；站点地址由 frpc 配置指定。

   尚无 Token 时，登录管理台创建用户 Token，再保存到对应账号的 token 文件。
   已有有效 Token 时，无需登录网页即可查看文档并下载配置。
   文档和配置不需要 Cookie 或 Authorization；实际连接 frpc 必须有有效 Token。
   官方 frpc 不会解析 default.txt；上述查找由读取本指南的 LLM/操作者完成，
   不需要新的账号选择启动器。配置中的路径一旦确定，修改 default.txt 不会
   自动改变已配置或运行中的 frpc；切换账号时重新选取路径并重启客户端。

Token 身份查询 API（供 LLM/客户端使用）
   GET https://manager.u.clock-p.com/api/token/me
   Authorization: Bearer <token>

   这里只接受 Authorization 请求头中的原始用户 Token，不需要网页登录或 Cookie。
   <token> 是占位符，使用实际 Token 替换；不要放在 URL 查询参数中。
   成功：HTTP 200，JSON 示例：{"username":"alice"}
   失败：缺失、错误、过期、撤销的 Token 或停用账号均返回 HTTP 401。
   非 GET 请求返回 HTTP 405。不会签发 token2、设置登录 Cookie 或返回 Token 内容。

   保存新凭据的顺序：调用接口 → 校验返回的 username → 保存到该账号目录/token
   → 按上面的规则设置 default.txt → 把 token 文件绝对路径写入 frpc 配置。
   使用本地已有凭据时，先按指定账号/default.txt 选择文件，再调用接口核对身份。
   返回 username 与选择的目录名不一致时报告，不尝试其他 Token、不静默改名或切换。
   接口失败或网络不可达时，报告问题，不根据目录名猜测真实身份。
   调用时不要把真实 Token 写进终端命令参数、日志或聊天；从文件或安全输入读取，
   使用 HTTP 库设置 Authorization 请求头。接口响应仅包含 username，可供目录命名。

2. Linux x64 下载客户端与配置
   curl -fSLo frpc_linux_amd64.zip https://u.clock-p.com/downloads/frpc_linux_amd64.zip
   unzip frpc_linux_amd64.zip
   chmod +x frpc
   curl -fSLo frpc.toml https://manager.u.clock-p.com/frpc.toml

   每台客户端单独下载配置。每次下载都会生成随机连接命名空间。
   配置中的顶层 user 不是账号用户名，保留自动生成的值即可。
   下载不会创建账号、Token 或服务。

3. 修改配置
   name：服务短名，例如 code；只使用小写字母、数字、连字符。
   localIP / localPort：要转发的本地服务地址与端口。
   subdomain：保持 auto，由服务端替换成真实域名。
   auth.oidc.tokenSource.file.path：按第 1 步找到的 token 文件的绝对路径。
   模板中的 /ABSOLUTE/PATH/TO/SELECTED/ACCOUNT/token 必须替换，不能原样启动。
   展开 ~ 或 %APPDATA% 为真实路径；Windows 可用正斜杠避免 TOML 转义问题。
   Linux 示例：/home/example/.frp.clock-p.com/alice/token
   Windows 示例：C:/Users/example/AppData/Roaming/frp.clock-p.com/alice/token
   上面均为路径示例，不能将 example 或 alice 当作默认账号。
   不填写完整域名或 customDomains；顶层 user 保留随机连接命名空间。

4. 启动
   ./frpc -c frpc.toml
   首次注册会自动登记服务，无需在管理台预先创建实例。
   例如 Token 属于 alice，name 为 code，实际地址是：
   https://code-alice-user.u.clock-p.com/
   账号部分始终由服务端根据 Token 确定；客户端不能冒用其他账号。
   完整域名标签最多 63 个字符。

5. 访问与权限
   新服务默认私有，在浏览器中访问时按提示登录。
   可以在管理台设为公开或共享给其他账号；重连不会重置权限。
   私有服务的 API/WebSocket 请求需要有效的实例会话，无会话返回 401。
   一个用户 Token 可用于多个服务。不同账号可以使用相同服务短名。
   撤销 Token 后，新连接和后续心跳校验会被拒绝。

Windows x64
   下载 https://u.clock-p.com/downloads/frpc_windows_amd64.zip 并解压。
   curl.exe -fSLo frpc.toml https://manager.u.clock-p.com/frpc.toml
   把 transport.tls.trustedCaFile 改成本机可信 CA PEM 文件路径。
   按第 1 步选择账号、保存 token 并填入绝对路径，然后执行：.\frpc.exe -c frpc.toml
   Windows 程序的运行体验尚未在本环境实测。

Windows 长期部署：计划任务（登录后启动）
   借鉴旧站 helper2 的计划任务方式，直接运行官方 frpc.exe。
   此模式需要当前 Windows 用户保持登录；锁屏可以继续运行，注销后不保证运行，
   也不承诺无人登录时开机自启。任务使用当前用户、Interactive、Limited，
   不保存 Windows 密码，不建立 SYSTEM 服务。
   先按上文由 LLM/操作者读取 default.txt（或用户指定账号），通过 /api/token/me
   核对身份并填写 token 绝对路径；下面脚本不负责选择账号，也不读取 Token 内容。

   A. 固定安装目录
   推荐 %APPDATA%/frp.clock-p.com/<username>/frpc/u.clock-p.com/<服务名>/，放置 frpc.exe、
   frpc.toml、logs/；Token 仍在该账号目录的 token 文件，配置引用其绝对路径。
   不要长期从 Downloads 或临时解压目录运行。不同服务分别建立目录与计划任务。
   在实际运行 frpc 的 Windows 用户下打开 PowerShell，先设置变量：

   $ErrorActionPreference = 'Stop'
   $account = 'REPLACE_WITH_VERIFIED_USERNAME'
   $instance = 'code'
   if ($account -cnotmatch '^[a-z0-9]{2,32}$') { throw '先填写已通过 API 核对的账号名' }
   if ($instance -cnotmatch '^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$') { throw '服务名不合法' }
   $rootDir = Join-Path $env:APPDATA 'frp.clock-p.com'
   $accountDir = Join-Path $rootDir $account
   $installDir = Join-Path (Join-Path (Join-Path $accountDir 'frpc') 'u.clock-p.com') $instance
   $exe = Join-Path $installDir 'frpc.exe'
   $config = Join-Path $installDir 'frpc.toml'
   $logs = Join-Path $installDir 'logs'
   $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
   $taskName = 'Frpc-u.clock-p.com-' + $sid + '-' + $account + '-' + $instance
   New-Item -ItemType Directory -Path $installDir, $logs -Force | Out-Null
   Write-Output $installDir

   将下载包中的 frpc.exe 和已按上文修改好的 frpc.toml 放进此目录。
   首次安装不要覆盖已有部署；已存在任务时走下面的更新步骤。

   B. 配置重连、心跳和日志
   在 frpc.toml 顶层（所有 [[proxies]] 或其他表头之前）增加以下设置。
   已有同名配置时修改原值，不要重复追加：

   loginFailExit = false
   transport.heartbeatInterval = 30
   transport.heartbeatTimeout = 90
   log.to = "./logs/frpc.log"
   log.level = "info"
   log.maxDays = 7
   log.disablePrintColor = true

   loginFailExit=false 让初次登录失败时继续重试，适合登录 Windows 后网络尚未就绪。
   显式心跳配合服务端超时检查；保留 HeartBeats/NewWorkConns 鉴权 scopes。
   日志路径相对计划任务固定的工作目录，按 frpc 的日志保留策略保存 7 天。
   保留可信 CA PEM 配置及 token 绝对路径，不使用 debug/trace 输出凭据。

   C. 注册并立即启动（继续在同一个 PowerShell 窗口执行）

   if (!(Test-Path -LiteralPath $exe -PathType Leaf)) { throw '安装目录缺少 frpc.exe' }
   if (!(Test-Path -LiteralPath $config -PathType Leaf)) { throw '安装目录缺少 frpc.toml' }
   if (Get-ScheduledTask -TaskName $taskName -TaskPath '\' -ErrorAction SilentlyContinue) {
       throw '同名任务已存在，请按更新步骤处理，不重复安装'
   }
   $running = @(Get-CimInstance Win32_Process -Filter "Name='frpc.exe'" | Where-Object ExecutablePath -eq $exe)
   if ($running.Count) { throw '此目录的 frpc 已运行，请先正常停止对应进程再安装任务' }
   Push-Location $installDir
   try {
       & $exe verify -c $config
       if ($LASTEXITCODE -ne 0) { throw 'frpc 配置检查失败，未注册任务' }
   } finally { Pop-Location }
   $action = New-ScheduledTaskAction -Execute $exe -Argument ('-c "{0}"' -f $config) -WorkingDirectory $installDir
   $trigger = New-ScheduledTaskTrigger -AtLogOn -User $sid
   $principal = New-ScheduledTaskPrincipal -UserId $sid -LogonType Interactive -RunLevel Limited
   $settingsArgs = @{
       ExecutionTimeLimit = [TimeSpan]::Zero
       RestartCount = 3
       RestartInterval = New-TimeSpan -Minutes 1
       MultipleInstances = 'IgnoreNew'
       AllowStartIfOnBatteries = $true
       DontStopIfGoingOnBatteries = $true
       StartWhenAvailable = $true
   }
   $settings = New-ScheduledTaskSettingsSet @settingsArgs
   Register-ScheduledTask -TaskName $taskName -TaskPath '\' -Action $action -Trigger $trigger -Principal $principal -Settings $settings | Out-Null
   Start-ScheduledTask -TaskName $taskName -TaskPath '\'

   任务没有运行时长上限；非零退出后每分钟重试，最多 3 次；不无限重启配置错误。
   IgnoreNew 只阻止同一个任务重复启动，不会阻止手动启动第二份 frpc。
   若注册任务被权限策略拒绝，使用同一用户的“以管理员身份运行”重新执行；
   不切换到另一 Windows 账号，否则用户目录和登录触发身份会改变。

   D. 检查、停止与恢复

   Get-ScheduledTask -TaskName $taskName -TaskPath '\' | Select-Object TaskName, State, Principal
   Get-ScheduledTaskInfo -TaskName $taskName -TaskPath '\' | Select-Object LastRunTime, LastTaskResult
   Get-Content -LiteralPath (Join-Path $logs 'frpc.log') -Tail 50
   # 临时停止并禁止下次登录/失败重启
   Disable-ScheduledTask -TaskName $taskName -TaskPath '\' | Out-Null
   Stop-ScheduledTask -TaskName $taskName -TaskPath '\'
   # 需要恢复时才执行以下两行
   Enable-ScheduledTask -TaskName $taskName -TaskPath '\' | Out-Null
   Start-ScheduledTask -TaskName $taskName -TaskPath '\'

   上面停止/恢复命令按需执行，不要把整段当作安装后的必跑步骤。
   Running 只说明进程运行，不代表已鉴权或能转发；还需检查日志、管理台实例
   以及实际访问服务，保持连接超过 2 分钟以覆盖心跳周期。LastTaskResult 在运行中
   可能显示任务仍运行的状态值，不能只用是否为 0 判断连接是否成功。
   本地被转发服务也需要自行长期运行；此任务只维护 frpc。

   E. 更新或卸载
   更新前先禁用并停止此任务，确认该安装路径的 frpc 进程已退出。
   将旧 frpc.exe、frpc.toml 复制到受限权限的时间戳备份目录，并使用
   Export-ScheduledTask -TaskName $taskName -TaskPath '\' 保存任务 XML。
   再替换程序/配置，执行 frpc verify，通过后启用并启动原任务。
   更新失败保持任务停用，人工检查和选择备份；不要覆盖 token/default.txt。
   原目录、任务名与账号保持不变；若要换账号，重新核对 Token 并单独建立部署。
   卸载时先禁用、停止，再执行：
   Unregister-ScheduledTask -TaskName $taskName -TaskPath '\' -Confirm
   不自动删除账号凭据或其他服务的目录。

   本节为部署示例，已对照官方参数及 frpc 配置检查；尚未做 Windows 实机
   计划任务、登录启动或注销行为验收。参考：
   https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtasksettingsset
   https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtaskprincipal
   https://gofrp.org/en/docs/reference/client-configures/

常见问题
   401：文档与配置下载不需要登录；私有实例访问和管理 API 需要登录。
   注册失败：检查 Token 是否有效、服务是否停用、名称是否过长，以及
   subdomain 是否为 auto；不要指定自定义域名或共享路由。
   转发失败：先确认 localIP/localPort 指向的服务能在客户端机器上访问。
   TLS 错误：使用正确的可信 CA 文件，不要关闭证书验证。

兼容性：当前使用官方 frpc 0.71.1，支持 HTTP / WebSocket 转发。
不使用旧飞书 --bridge-token 扩展；当前管理模式不提供通用 TCP/RD Gateway。
