tmphost

tmphost.io

Go（Fiber v3、GORM）后端和 Vue 3（Vite、Tailwind）前端。

HTTP API（/api/v1、登录、OAuth 2.1 服务端、公开文件 URL 和 /mcp）在 openapi.yaml（OpenAPI 3.1）中有说明。缺少路由会导致后端测试失败，因此请确保该文件与 backend/internal/handler/api/api.go 保持同步。

登录和额度

• 使用 Google 或 GitHub（OAuth）登录。账户以已验证的电子邮件地址为键，因此两个提供商都会关联到同一个账户。
• 新账户初始获得 1000 次操作额度（注册赠送额度， TMPHOSTIO_CREDITS_SIGNUP_GRANT）。每 30 天获得 250 次操作额度 （月度赠送额度，TMPHOSTIO_CREDITS_MONTHLY_GRANT）：每天 00:00 UTC 运行的 cron 作业会将到期账户的额度重置为 250（未使用的额度不结转），并将其续期时间向后推 30 天。
• 每次余额变更都会记录在 credit_activities 中，并与余额变更在同一事务中写入：ops（以 uint8 存储：grant、renewal、spend、refund、admin_grant、expiry）、带符号的 change（+X 或 -Y），以及变更后的 current 余额。Credits 页面以图表显示过去 30 天的每日用量和余额，并列出历史记录（GET /api/v1/users/me/credits/activities?before=&limit=，按时间从新到旧排列）。

文件托管

• 文件存放在有过期时间（TTL）的文件夹中（默认 30 分钟，最长为 files.maxTtlMinutes，默认 7200 小时）。每个写入的文件，每满 1 MiB 大小，以及文件夹剩余有效期每满 30 分钟，需支付 1 点数：例如，一个 1.01 MB 的文件保留 1 小时，费用为 2 x 2 = 4 点数。
• 可以向已有文件夹添加文件（Web 应用、MCP uploadFile 配合 folderId、CLI --id）。上传到已有路径的文件会被原位替换，即更新文件：其 URL 保持不变，文件夹的过期时间也不变。此次写入按常规费用计费。
• 可以延长文件夹的过期时间（Web 应用、MCP extendFolder、CLI tmphost file extend、POST /api/v1/folders/:id/extend 配合 {"minutes": N}），但剩余有效期不得超过 TTL 上限。文件夹中的每个文件都会按上传费用计费：新增时间每满 30 分钟、文件大小每满 1 MB，需支付 1 点数。空文件夹免费。
• 文件夹可以要求访客输入 6 位 PIN。在 Web 应用的“安全”页面设置账户 PIN，可保护所有文件夹：可以使用固定 PIN，也可以使用身份验证器应用生成的验证码（TOTP，使用 QR 码设置）。关闭此功能后，Agent 创建的每个文件夹都可以获得各自的随机 PIN，也可以按需为任何文件夹设置 PIN（Web 应用、MCP uploadFile 配合 pin 或 addPinToFolder、CLI --pin 或 tmphost file pin、POST /api/v1/folders/:id/pin）；PIN 会以 bcrypt 哈希形式存储，并且只显示一次。访客可通过打开带有 ?pin=123456 的链接，或在页面上输入 PIN 来访问；随后，文件夹会通过 Cookie 允许访客访问，直至 Cookie 过期。每个文件夹、每个地址在一分钟内输错 PIN 两次后，会返回 429，直至这一分钟结束。
• 无需登录，Web 应用的“上传”页面即可创建文件夹，其有效期最长为 files.anonymousMaxTtlMinutes（默认 10 分钟；root 可在 /setup 页面修改 TMPHOSTIO_FILES_ANONYMOUS_MAX_TTL_MINUTES）。
• 文件存储在本地磁盘（TMPHOSTIO_STORAGE_LOCAL_PATH）或 S3 存储桶中，路径格式为 u<userId>/<folderId>/<path>。路径最多可包含 5 层目录，并由服务器端验证，因此文件不会离开其所属文件夹。数据库会存储每个文件夹的 ID、所有者和过期时间，以及其中各文件的大小、类型和更新时间（因此列出文件和重定向时无需调用存储服务），但绝不存储文件内容；每分钟运行一次任务，删除过期文件夹。文件夹 ID 为 8 个随机小写 base36 字符，因此无法猜出公开 URL。
• 上传的文件也会保存在内存中并直接从内存提供服务，且没有时间限制，总量上限为 256 MB（TMPHOSTIO_STORAGE_CACHE_MAX_MB，优先移除最近最少使用的文件；设为 0 可关闭）。删除文件或文件夹时，也会将其从内存中移除。使用 S3 时，文件进入内存后即会返回上传成功，并在后台写入存储桶（TMPHOSTIO_STORAGE_CACHE_ASYNC，默认开启）：同一路径的写入会按顺序完成，失败时重试 3 次；写入完成前，文件会从内存中列出并提供服务，且会在关闭前完成写入。当正在写入的文件总量超过 256 MB 时，上传会等待存储桶响应。
• 使用 S3 时，可选的预热缓存（设置页面 → 存储，默认关闭）也会将小于 1 MB 的文件保存在服务器磁盘上，存放于设置文件旁的 warm/ 目录中（Docker 中为 /data/warm），默认上限为 1024 MB（优先移除最近最少使用的文件，不设过期时间）。上传的文件先写入磁盘，再写入存储桶；失败时会按指数退避重试（1s、2s、4s……），重试次数由设置页面配置（默认为 0）。如果存储桶写入仍然失败，会再次移除磁盘副本；从存储桶读取文件时，也会将副本写入磁盘。删除文件时会移除副本。启动时会清空该目录。
• 文件夹查询也会缓存在内存中，总量上限为 64 MB（TMPHOSTIO_CACHE_FOLDERS_MAX_MB，优先移除最近最少使用的文件夹；设为 0 可关闭）。只有写入或删除文件夹时才会将其移除（不会因过期时间变化而移除）；下次查询时会重新从数据库读取。
• 使用 S3 时，通过公开 URL、API 和 CLI 下载大于 1 MB 的文件（TMPHOSTIO_STORAGE_REDIRECT_OVER_MB，设为 0 可关闭）时，会返回 302 Found，并重定向到有效期为 15 分钟的存储桶签名 URL（TMPHOSTIO_STORAGE_REDIRECT_TTL），因此大型文件不会经过 tmphost。HTML 文件（.html、.htm，无论大小及访问路由）、仍在内存中的文件，以及 MCP 下载（base64Content/textContent）会直接提供。
• 公开 URL 默认格式为 <TMPHOSTIO_BASE_URL>/files/<userId>/<folderId>/<path>；启用子域名后（TMPHOSTIO_FILES_SUBDOMAINS、TMPHOSTIO_FILES_PUBLIC_DOMAIN，默认为站点域名），格式为 <folderId>.<publicDomain>/<path>。这需要通配符 DNS 和证书；内置 TLS 在站点域名作为公开域名时会自动获取证书。所有文件都会通过 Content-Security-Policy: sandbox 提供，因此托管页面永远不会使用应用的源。
• Markdown 文件（.md、.markdown）会原样提供；添加 ?format=html 时，则会显示为阅读页面：GitHub 风格的 Markdown（表格、任务列表、删除线、脚注）呈现在宽幅衬线字体栏中，并根据访客的浅色或深色主题显示，标题取自首个 # 标题。源文件中的原始 HTML 和 javascript: 链接会被省略。

MCP、CLI 和 OAuth

• /mcp 是一个无状态 MCP 服务，每项操作对应一个工具： uploadFile、downloadFile、listFiles、getUrl、extendFolder 和 addPinToFolder，每个工具都以 folder 作为 folderId。它运行在应用 URL 上，并且在设置了 MCP 域名时也运行在该域名上（https://<mcp domain>/mcp）。cli/ 中的 tmphost CLI 与其功能一致。 文件内容通过 base64Content 传输（默认方式），或者在 format 参数指定时通过 UTF-8 textContent 传输。 它还通过 MCP Skills 扩展（io.modelcontextprotocol/skills， SEP-2640）提供 tmphost Agent Skill（工具最佳实践）： skills/list 和 skills/get 用于描述该技能， resources/read 返回 skill://tmphost/SKILL.md，而 resources/directory/read 会列出该技能的目录（directoryRead）。该技能位于 backend/internal/handler/mcp/skills。
• 两者都使用 tmphost 自有的 OAuth 2.1 服务登录：动态客户端 注册（/oauth2/register）、PKCE S256、同意页面 （/oauth2/authorize）和刷新令牌（/oauth2/token），通过 /.well-known/oauth-authorization-server 和 /.well-known/oauth-protected-resource/mcp 发现。CLI 使用内置的 公共客户端 ID 00000000001 配合环回重定向；如果浏览器无法访问 CLI（SSH、容器），则使用设备授权流程（RFC 8628）： /oauth2/device/code 会发放一个代码，用户在 /auth/device 输入该代码， 同时 CLI 轮询 /oauth2/token。访问令牌也可作为 Bearer 令牌用于 /api/v1。MCP 域名本身也是一个 issuer（https://<mcp domain>），其注册和令牌端点均位于该主机上； 用户则在应用 URL 的 /oauth2/mcp/authorize 登录并授权，该端点会以 MCP 域名的 iss 响应。

Claude Code 插件

plugin/claude 是一个 Claude Code 插件，添加了 /mcp 服务和 tmphost 技能（何时以及如何与其共享文件）。此 仓库也是它的市场（.claude-plugin/marketplace.json）：

/plugin install tmphost --marketplace tmphost/tmphost
# or, in two steps:
/plugin marketplace add tmphost/tmphost
/plugin install tmphost@tmphost

它连接到 https://mcp.tmphost.io/mcp。Claude Code 会在首次调用工具时通过 浏览器登录。对于可自托管的服务，请自行添加 MCP 服务，而不是使用插件： claude mcp add --transport http tmphost https://mcp.example.com/mcp。 其列表图标为 plugin/claude/.claude-plugin/icon.png （1024 px，由 favicon-light.svg 渲染），隐私政策位于 https://tmphost.io/privacy。 CI 会对两个清单运行 claude plugin validate --strict，并检查 图标和隐私政策 URL。

Gemini CLI 扩展

此仓库也是一个 Gemini CLI 扩展：gemini-extension.json 添加了位于 https://mcp.tmphost.io/mcp 的 MCP 服务，并将 plugin/gemini/GEMINI.md（何时以及如何与其共享 文件）加载到每个会话中。

gemini extensions install https://github.com/tmphost/tmphost

Gemini CLI 通过浏览器登录（/mcp auth tmphost）。关于可自托管的服务，请参阅 plugin/gemini。

Codex 和 ChatGPT 插件

plugin/codex 是一个可移植的 Agent Plugins 软件包，供 Codex 和 ChatGPT 使用，包含 MCP 服务和 tmphost 技能。此 仓库是它的市场（.agents/plugins/marketplace.json）：

codex plugin marketplace add tmphost/tmphost
codex plugin add tmphost@tmphost

Codex 会在首次调用工具时通过浏览器登录。CI 会根据 OpenAI 的目录提交规则和 Agent Plugins 架构检查该软件包，使用 Codex CLI 安装，并上传 ZIP 文件以供提交；详情请参阅 plugin/codex。

开发

cp backend/cmd/server/.env.example backend/cmd/server/.env   # fill in OAuth apps, JWT secret, master key
set -a; . backend/cmd/server/.env; set +a
make dev            # both at once (Ctrl-C stops both), or separately:
make dev-backend    # API on :2027
make dev-frontend   # app on http://localhost:5173 (proxies /api)

需要注册的 OAuth 回调 URL：<app URL>/auth/<provider>/callback （google、github 或自定义提供商的 ID；设置页面会显示每个回调 URL）。

数据库：默认使用 SQLite（TMPHOSTIO_SQLITE_DSN）；设置 TMPHOSTIO_POSTGRES_ENABLED=true 和 TMPHOSTIO_POSTGRES_DSN （postgres://user:password@host:5432/tmphost?sslmode=disable）以使用 PostgreSQL。

构建和测试

make build   # bin/tmphost with the frontend embedded
make test    # 100% coverage is enforced on both sides

可安装应用（PWA）

Web 应用可作为 PWA 安装（frontend/public/manifest.webmanifest、 frontend/src/sw.js）。Service Worker 只会预缓存构建后的应用外壳； /api、/auth、/oauth2、/mcp 和文件夹文件始终通过网络加载。 打开的标签页会在加载时、每小时以及重新显示时检查新版本，在后台下载更新并显示进度条，然后提供“立即更新”选项，点击后会将所有打开的标签页重新加载到新版本。Service Worker 仅在生产构建中注册（npm run build），在 npm run dev 下不会注册。

管理页面

/admin 也只能使用根访问令牌打开（一次根账号登录即可访问 /setup 和 /admin）。根账号可以向单个用户（按电子邮件地址）或 所有用户授予积分（使用 POST /admin/v1/credits/grants，并传入 {"credits": 500, "email": "[email protected]"} 或 {"credits": 500, "all": true}）。 授予的积分会保存在 credit_grants 中，并记录为 admin_grant。积分将在 30 天后的下一个 00:00 UTC 到期，届时每日任务会收回剩余积分（记录为 expiry）。每月续期不会重置这些积分，消费时会优先扣除最早到期的积分。

管理页面还会显示所有账号的统计数据（用户数、持有的积分、 已使用的积分、过去 30 天每天的注册人数、在线文件夹），以及可按电子邮件地址、姓名或用户 ID 搜索的用户列表。每位用户的页面会显示其余额、使用情况、在线文件夹和完整的积分历史。管理 API 位于 /admin/v1 下，与公开的 /api/v1 分开，且不属于 openapi.yaml。

设置页面

/setup 只能使用根访问令牌（TMPHOSTIO_AUTH_ROOT_ACCESS_TOKEN）打开； 如果该令牌为空，启动时会生成一个随机令牌并打印出来。在此页面中，你可以更改注册和每月赠送的额度、最大 TTL 和公共 URL 模式（这些设置会立即生效），以及以下设置（需要重启后生效）：

• 域名：应用 URL（默认为 http://localhost:2027；例如 https://app.tmphost.io，可使用任意域名或子域名）和站点域名（例如 tmphost.io）。 服务器会响应动态子域名 <8 characters>.<sites domain>；还可以设置可选的 MCP 域名（例如 mcp.tmphost.io、TMPHOSTIO_MCP_DOMAIN），该域名仅提供 /mcp、其 OAuth 元数据以及 OAuth 注册和令牌端点，因此 MCP 客户端连接到 https://mcp.tmphost.io/mcp。其他主机名会返回 404； localhost 始终会访问应用。
• TLS：在专用端口（默认为 443）上提供 HTTPS，并将应用端口重定向到该端口。证书由 Let's Encrypt 自动签发（使用 lego 和 TLS-ALPN-01 挑战，因此 Let's Encrypt 必须能通过端口 443 访问服务器），在有效期不足 30 天时续期，并加密后缓存到设置文件旁边。
  • 应用主机和 MCP 域名：各自始终使用独立证书。
  • 动态子域名（可切换）：每个子域名首次访问时都会获取独立证书（Let's Encrypt 对每个已注册域名每周最多允许签发约 50 个新证书）；或者，使用可选的 Cloudflare API 令牌，通过 DNS-01 获取一个 *.<sites domain> 通配符证书，不受此限制。
• 数据库（SQLite 或 PostgreSQL）和文件存储（本地磁盘或 S3）。
• 文件：最大 TTL 和上传大小，以及文件夹是通过路径提供服务，还是通过 <folder ID>.<public domain> 子域名提供服务。
• 登录提供方：Google、GitHub，以及任意数量的自定义 OpenID Connect 提供方（名称、SVG 图标、客户端 ID、客户端密钥、身份验证 URL，即颁发者；端点从其 /.well-known/openid-configuration 获取）。

设置会保存到 TMPHOSTIO_SETTINGS_FILE（默认为 ./_storage/settings.json，权限模式为 0600），并覆盖配置文件和环境变量。设置页面上的密钥（包括 PostgreSQL DSN）只能写入，不能读取。

• 静态加密：文件使用从 TMPHOSTIO_MASTER_KEY 派生的密钥（HKDF-SHA256）进行 AES-256-GCM 加密。主密钥只从环境中读取，绝不会从 YAML 或设置文件中读取，且必须至少包含 32 个字符（openssl rand -hex 32）；没有该密钥，服务器将无法启动。密钥错误或文件遭篡改时，启动会报错并停止；如果密钥丢失，请删除该文件并重新输入设置。
• 绝不提供文件：服务器只提供内嵌的前端，以及其中的 Web 资源文件类型（.js、.css、.svg 等）。

Docker

单个镜像，单个二进制文件：前端和基础配置均已内嵌，镜像（FROM scratch，以 nobody 用户运行）仅包含二进制文件和 CA 证书。

make docker
docker run -p 2027:2027 -v tmphost-data:/data \
  -e TMPHOSTIO_MASTER_KEY=... -e TMPHOSTIO_AUTH_JWT_SECRET=... -e TMPHOSTIO_AUTH_ROOT_ACCESS_TOKEN=... \
  -e TMPHOSTIO_BASE_URL=https://app.tmphost.io tmphost

设置和 SQLite 数据库存储在 /data 卷中。