---
title: HanteleWorkTime 维护手册
type: curated
permalink: main/projects/6553b53c-bf14-49e3-a3de-1ee2f3533d51/curated/development/hantele-work-time-维护手册
stable_id: 6c2974c0-4721-48b6-9655-745316b7472c
scope: project
project_id: 6553b53c-bf14-49e3-a3de-1ee2f3533d51
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: maintenance
revision: 1
source_memory_ids: []
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: null
source_git_commits: []
source_agent_sync_ids: []
model_connection: Sub2API
model_name: git-restore
source_count: 13
source_revisions: {}
source_dispositions:
  processed: 13
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids: []
job_cited_source_ids: []
conflicts: []
supersedes: []
preferences: []
source_cursor: 207
source_hash: 5a2bf7e4aa8a90513e133f70e1737cdaf99fddd9888166c7645ba4700934109c
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-08-31T03:10:15.092752+00:00'
updated_at: '2026-09-23T14:56:45.715505+00:00'
tags:
- maintenance
- development
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

# HanteleWorkTime 维护手册

本手册针对 **HanteleWorkTime** 工作区（development）提供日常运维、记忆更新以及凭证管理的最佳实践。

## 1. 记忆（Project Context）管理
- 所有开发、运维、故障排查笔记统一写入 `aidocs/project_context.md`。
- 文件结构：固定标题行后，以 **最新优先**、秒级时间戳(`YYYY-MM-DD HH:MM:SS`) 追加条目，记录 **做了什么、为何、如何验证、遇到的问题、后续计划**  [来源: `global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e`]
- `aidocs/` 已加入 `.gitignore`，永不提交至代码库；完成任务后执行 **清理临时文件、调试日志、无用代码**，再提交有意义的代码改动。提交信息格式为 `type: 中文一句话描述`（如 `feat: 修复登录超时`）  [来源: `global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e`]

## 2. Git 工作流
- 默认 **仅 commit**；除非明确要求 `push`，系统不会自动推送。  [来源: `global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e`]
- 提交类型约定：`feat`, `fix`, `refactor`, `style`, `docs`, `chore`, `revert`，后接中文简要描述。  [同上]
- 非当前会话的合理修改（不含敏感信息）在确认不破坏代码后一起提交。  [来源: `global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e`]

## 3. 凭证检索与更新工作流
- **登录/SSH/数据库/API** 前统一走 **Vaultwarden** 检索流程。唯一匹配自动使用，多条或无匹配时提示人工选择。  [来源: `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`]
- 新增或修改的 **密码、Token、API‑Key、TOTP 种子** 必须立即写入密码库；记忆中仅记录名称、用途、使用方式，绝不保存明文。  [同上]
- 目前受管基础设施列表：BDYG18Pro、OpenWrt、MySQL、MemRelay、Gitea OAuth、FRP Token、公网 FRPS 服务器。  [同上]

## 4. 常规维护任务
| 任务 | 频率 | 关键步骤 |
|------|------|----------|
| 检查 Docker 代理 | 每次 Docker 重启后 | 确认 `http://127.0.0.1:7897` 已在 Docker Desktop 手动代理中配置并生效  [来源: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`] |
| 更新项目记忆 | 每次功能迭代或故障排查后 | 在 `aidocs/project_context.md` 追加最新条目，确保时间戳精确到秒 |
| 验证凭证可用性 | 每周一次 | 使用检索到的凭证尝试登录对应服务，确认无失效或权限变化 |
| 清理临时文件 | 每日 | 删除容器内部的 `/tmp`、日志文件以及本地调试产生的 `.log` |
| 代码审查 | 每次合并前 | 确认不引入不必要依赖，遵守 KISS 与 YAGNI 规范  [来源: `global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5`] |

## 5. 故障排查要点
- **Docker Exec 超时**：默认 3 秒超时会导致长连接中断。获取裸 socket 后调用 `settimeout(None)` 以保持无限阻塞  [来源: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`]
- **FastAPI async 坑**：在 `async def` 中调用阻塞 I/O（如 pymysql、requests）会冻结事件循环。改为普通 `def`，FastAPI 会自动转入线程池  [来源: `global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0`]
- **凭证未自动使用**：确保 Vaultwarden 条目唯一，若出现多条需手动确认；若无匹配则需手动输入或创建新条目  [来源: `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`]

---

**标签**: ["maintenance","development"]