TSS Portal
使用指南

• 生产（Prod）：https://tss.umu.work — 日常正式使用，推荐 UMU SAML SSO 登录
• 灰度（Gray）：https://tss-portal.top — 发版前验证、远程办公、应急通道
• 本地（Local）：http://localhost:3000 — 开发调试

三环境共用同一份代码（同一 Git 仓库），但各自维护独立 SQLite 数据，互不影响。

登录页已全英文化，只保留一个「Sign in with UMU account」按钮，点击后跳转 UMU 公司 SSO 完成认证。

• 使用公司账号 + MFA（已登录则免输）
• 单点登录，与公司 IT 统一管理
• 需要管理员提前将您的邮箱添加到白名单
• 支持 SLO（退出登录会结束 IdP 端会话）

• Google OAuth：登录页已移除按钮；其 Client ID 现主要供「Google Sheet 同步 / DevOps 监控面板」工具的浏览器直读使用
• 测试登录（BYPASS）：邮箱 + 访问码跳过 SSO，访问码来自 .env 的 BYPASS_SECRET。仅在内网环境显示入口（阿里云通过 HIDE_TEST_LOGIN=1 显式隐藏，留作兜底）

阿里云不能直连 googleapis.com，Google 验签用的公钥（每 1-2 周轮换一次）由 内网 pek01-tss 充当代理每日定时拉取并推送到阿里云。普通用户登录无任何感知。

• 自动续期：pek01-tss 上 admin 用户的 cron 0 9,21 * * *（每天 09:00 + 21:00）调用 /home/admin/bin/refresh-google-certs.sh，拉证书后 POST 到 /api/auth/inject-google-certs
• 管理员浏览器代拉（次路径）：管理员每次打开 /admin.html 时自动触发一次刷新；后台「外部接口配置」tab 底部「Google 公钥证书」卡片可手动「立即刷新」
• 缓存策略：登录路径带 5 秒超时 + 宽容缓存，即使 Google 临时不可达也不会 hang 死登录请求
• 排查日志：tss → sudo -u admin tail -20 /home/admin/var/log/refresh-google-certs.log（看到 OK: 已注入 X 把证书 即正常）

• 顶部 cat-tab 胶囊按钮「全部 / 分类 A / 分类 B / ...」
• 选「全部」：显示分类卡片网格，每张卡显示分类名 + 链接数量徽章
• 选具体分类：直接平铺该分类下所有链接
• 未分类的链接自动聚合到末尾的「其他」虚拟卡
• 图标由系统根据名称和描述自动分配（去重），无需手动选择

• 智能定位（视口边缘自动调整方向，不溢出）
• 列出该分类下所有链接（含个人链接，带「我的」徽章）
• 点 ESC / 点外部 / 滚动页面 → Popover 自动关闭
• 底部「+ 添加链接到此分类」→ 跳到管理页并预选当前分类

• 顶部胶囊按钮按工具分类过滤（PPT 制作 / 数据分析 / 邮件处理 / ...）；工具支持多分类（v2.12），一个工具可归入多个分类，选中任一所属分类都会显示
• 工具卡显示状态指示灯（在线 / 离线 / 检测中）
• 受权限和个人隐藏设置控制（在「我的工作台 → 工具设置」管理）

• 顶部 cat-tab 过滤栏（绿色风格）
• 「全部」显示项目分类卡片，点击弹 Popover 概览
• 选具体分类 tab → 平铺显示该分类下项目（保留绿色边框风格）
• 「+ 添加项目到此分类」→ 跳管理页预选分类

• 顶部默认分类 + 默认公开范围（每行可单独覆盖）
• 表格逐行填写：标题 / URL / 描述 / 分类 / 公开范围
• 支持粘贴 TSV/CSV：从 Excel / Notion / Google Sheets 直接复制粘贴整张表
• 分隔符自动识别（含制表符 → TSV，否则 CSV）
• 第一行如含「标题/title」「url/链接」字样会被识别为表头并跳过
• 行级修改自动脱离默认值（边框变色提示）
• 提交时图标自动分配，事务原子性（要么全部成功要么全部回滚）

• 侧边栏「项目分类」入口，同链接分类操作模式
• 项目编辑 Modal 增加「分类」下拉
• 项目管理表格增加「分类」列
• 支持用户私有项目分类（在「我的工作台」管理）
• 删除分类时该分类下项目自动归到「其他」（ON DELETE SET NULL）

LLM 配置分为两层：

• 全局提供商凭证：在「LLM 配置」Tab 中设置 MiniMax 或 GLM 的 API Key、API URL、模型名称等
• 工具级配置：为「日报周报心得」「日语润色」等 AI 工具单独选择使用哪个提供商，并可自定义系统提示词

当 LLM 未启用、无 API Key 或余额不足时，系统自动回退到本地模板，不影响使用。

• 落地页：登录后直接跳 /utj.html（纯日语「マイツール」页，只列出被授权的工具 + 日语版「バグ報告」入口），看不到首页 / 后台 / 工作台
• 双层拦截：页面层 userCanAccess 仅放行被显式授权的工具（项目 / 链接一律 403）；API 层 utj-api-guard 按「工具 → API 前缀」映射拦截未授权调用
• 只读约束：在「SSO 证书监控」「访问计划监控」中 UTJ 锁定日语并隐藏语言切换，且只能查询 / 下载，写操作（新增、编辑、删除、批量、同步 Sheet、收件人管理等）全部隐藏
• 授权方式：管理后台「用户管理」逐用户勾选可访问的工具

• 公开（all）：所有登录用户均可看到
• 仅分配（assigned）：只有在 user_content_access 表中被授权的用户才能看到
• 个人（private）：仅创建者自己可见（user_id 关联）

当管理员把某条内容的 visibility 从 assigned 改为 all 时，系统会自动删除该内容在 user_content_access 中的所有授权记录。

为什么？ 防止以后切回 assigned 时旧授权意外恢复（曾发生过：原本只授权给 A 用户，后改成全员公开，再后来又改回限定状态，结果 A 用户依然能看，造成困惑）。

之前 /projects/<slug> 和 /tools/<dir>/* 是纯静态资源，知道 URL 即可访问。现已加入服务端鉴权：

• 未登录访问 → 自动 redirect 到 /login.html（HTTP 302）
• 登录但无权限 → 返回 403 友好提示页（含「返回首页」按钮）
• 资源文件（.css/.js/图片等）放行（性能优化，安全边界在 HTML 入口）
• 认证机制：JWT 同时存 localStorage（API 调用）+ httpOnly Cookie（HTML 入口校验）

把指定环境的数据库 + 项目 HTML + 工具数据拉到本地：

# 灰度 → 本地
bash pull-data.sh

# 生产 → 本地
bash pull_tss.sh

共有的安全机制：

• Schema 安全预检：本地 init.js 比服务器新（说明你有未发布修改）会要求输入 yes 确认
• 本地服务停止检测：检查 3000 端口占用，让你停服防 DB 损坏
• WAL checkpoint：让 .db-wal 落入主库（防数据丢失）
• 本地 DB 备份：拷贝到 data/.backup-TIMESTAMP/，可随时回滚
• 同步 3 个 SQLite 文件（.db / .db-wal / .db-shm）+ projects HTML + 工具数据

阿里云出网受限拉不到 googleapis.com，且内网 pek01-tss 才是日常运营的真实环境。两条 cron 任务每天自动把缺失的能力补回阿里云：

• Google 证书续期：admin crontab 0 9,21 * * * → /home/admin/bin/refresh-google-certs.sh → 日志 /home/admin/var/log/refresh-google-certs.log
• DB 全量同步：root crontab 0 3 * * * → /root/bin/sync-db-to-aliyun.sh → 日志 /root/var/log/sync-db-to-aliyun.log

DB 同步流程（每晚 03:00）：

1. pek01-tss 上 sqlite3 .backup 在线快照（不停容器，WAL 模式安全）
2. scp 推到阿里云 /tmp/tss-snap-incoming.db
3. 阿里云：备份当前 DB 到 /var/backups/tss-db/tss_portal.YYYY-MM-DD.db（保留 7 天）→ docker stop tss_portal → 替换 DB → docker start tss_portal
4. 健康检查：HTTP 200/301/302，最多 25 秒；失败时自动从今日 backup 回滚

⚠️ 数据流单向：每天 03:00 阿里云被 pek01-tss 整库覆盖（包括 users 表）。阿里云上 03:00 之后的修改会在次日凌晨被回滚 —— 长期修改请到生产 tss.umu.work 上做。

• node_modules/ — 服务器独立安装
• data/ — 数据库文件（保留服务器生产数据）
• .env — 环境变量（各环境独立配置）
• server/config/saml-keys/sp-private.key — SAML SP 私钥（敏感，永远不入仓 / 镜像）
• .git/、.claude/、deploy.log — 本地专用
• design/、*.command、*.md 文档文件

不相通。生产 / 灰度 / 本地三环境共用一份代码，但各自独立 SQLite 数据库。需要在本地复现线上问题时，用 pull-data.sh（灰度）或 pull_tss.sh（生产）把数据拉到本地。

• 日常使用 → 生产 https://tss.umu.work（UMU SAML SSO）
• 内网网络不通时应急 → 灰度 https://tss-portal.top（UMU SAML SSO）
• 开发调试 → 本地 http://localhost:3000（测试登录 BYPASS）

• 登录页会显示英文错误提示，按提示操作即可
• 疑似服务端问题 → 联系管理员排查容器日志
• 应急通道：内网环境可用测试登录（BYPASS，邮箱 + 访问码），或由管理员临时启用 Google 兜底

需要管理员先将您的邮箱添加到用户白名单（管理后台 → 用户管理 → 新增用户）。

v2.11 起登录页已全英文化并精简为 Sign in with UMU account 一个入口（UMU SAML SSO）。Google 登录、测试登录已从页面移除；测试登录（BYPASS）仅在内网环境自动出现，供调试与紧急兜底。

请联系管理员在「用户管理」中重新启用账号。

• 该内容设置为「仅分配」且您不在分配列表中 → 联系管理员添加
• 该内容设置为「仅自己可见」且不是您创建的 → 正常
• 您在「工作台 → 工具设置」中隐藏了该工具 → 取消隐藏即可

这些功能受管理员的「权限设置」控制。若被关闭，对应 Tab 会自动隐藏。请联系管理员开启。

• 检查管理后台 LLM 配置是否已填写正确的 API Key
• 确认选择的提供商（MiniMax/GLM）账户余额充足
• 如 LLM 不可用，系统会自动回退到本地模板输出

需要管理员在「邮件配置」中填写正确的 Gmail OAuth Client ID，并确保已在 Google Cloud Console 中添加对应域名的授权来源。

确认服务器上 Playwright 浏览器依赖已正确安装。如是首次部署，请联系管理员在容器内执行 npx playwright install chromium。

• 确认本地与服务器之间网络通道已配置（灰度走 SSH，生产走 JumpServer）
• 查看 deploy.log 获取详细错误信息
• 灰度：检查 deploy.sh 输出的错误行号
• 生产：确认 git push 是否成功，新机 cron 兜底会在 2 分钟内补拉

部署脚本会在 DB 变更时自动备份。如需手动回滚，请联系管理员，按服务器上备份目录中的对应备份文件执行恢复。