chore: 导入旧记忆备份供恢复
This commit is contained in:
+69
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: HanteleWorkTime 常见问题排查指南
|
||||
type: curated
|
||||
permalink: main/projects/6553b53c-bf14-49e3-a3de-1ee2f3533d51/curated/development/hantele-work-time-常见问题排查指南
|
||||
stable_id: 6086d60a-bd33-4823-9117-10e1fdae2767
|
||||
scope: project
|
||||
project_id: 6553b53c-bf14-49e3-a3de-1ee2f3533d51
|
||||
workspace_type: development
|
||||
usage_profile_id: null
|
||||
preference_context: development
|
||||
document_type: troubleshooting
|
||||
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: openai/gpt-oss-120b
|
||||
source_count: 13
|
||||
source_revisions: {}
|
||||
source_dispositions:
|
||||
processed: 13
|
||||
unchanged: 0
|
||||
unsupported: 0
|
||||
skipped: 0
|
||||
cited_source_ids:
|
||||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||||
job_cited_source_ids:
|
||||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||||
conflicts: []
|
||||
supersedes: []
|
||||
preferences: []
|
||||
source_cursor: 207
|
||||
source_hash: 5a2bf7e4aa8a90513e133f70e1737cdaf99fddd9888166c7645ba4700934109c
|
||||
prompt_version: 2026-08-12.3
|
||||
schema_version: '3'
|
||||
curation_job_id: 831de31c-3ff7-4cb5-81ed-55b900461a33
|
||||
created_at: '2026-08-31T03:10:09.738999+00:00'
|
||||
updated_at: '2026-08-31T03:10:09.739616+00:00'
|
||||
tags:
|
||||
- development
|
||||
- troubleshooting
|
||||
---
|
||||
|
||||
## 常见问题及解决方案
|
||||
|
||||
| 场景 | 症状 | 可能原因 | 解决办法 |
|
||||
|------|------|----------|----------|
|
||||
| **FastAPI 异步阻塞** | 请求卡死，日志无响应 | 在 `async def` 中调用阻塞 I/O（如 `pymysql`、`requests`） | 将函数改为普通 `def`，让 FastAPI 自动切换至线程池。 |
|
||||
| **PowerShell 发送 JSON** | 服务器收到的 JSON 丢失引号 | 直接在命令行中使用 `--data` 导致引号被解析 | 先将 JSON 写入临时文件，然后使用 `--data-binary @file` 发送。 |
|
||||
| **Docker Exec 超时** | 长时间交互式命令在 3 秒后断开 | `docker-py` 默认全局超时被继承到 hijacked socket | 在获取裸 socket 后调用 `socket.settimeout(None)`，保持无限阻塞。 |
|
||||
| **Docker Hub 连接失败** | `docker pull` 报错或长时间卡住 | Docker Desktop 代理未配置为 *Manual* 或代理地址错误 | 打开 Docker Desktop → Settings → Resources → Proxies，手动填写 `http://127.0.0.1:7897`，保存并重启 Docker。 |
|
||||
| **Vaultwarden 凭证未自动使用** | 登录或 API 调用仍要求手动输入凭证 | 搜索到多条或无匹配记录 | 确认 Vaultwarden 中仅保留唯一条目；若有多条，手动选择或删除冗余。 |
|
||||
| **Docker 容器网络不可达宿主服务** | 容器内访问 `localhost` 失败 | 容器默认隔离网络 | 使用 `host.docker.internal`（Windows/macOS）或在 `docker run` 时添加 `--network host`（Linux）访问宿主。 |
|
||||
| **脚本换行符导致错误** | `$'\r': command not found` | 脚本使用 Windows CRLF 换行 | 将脚本转换为 LF 换行（`dos2unix` 或编辑器设置）后重新执行。 |
|
||||
|
||||
**参考来源**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`, `global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0`, `global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5`, `global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d`, `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`.
|
||||
|
||||
**标签**: ["development", "troubleshooting"]
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: HanteleWorkTime 系统架构概览
|
||||
type: curated
|
||||
permalink: main/projects/6553b53c-bf14-49e3-a3de-1ee2f3533d51/curated/development/hantele-work-time-系统架构概览
|
||||
stable_id: fb9a56e2-56ce-4d5a-9334-79c18192d663
|
||||
scope: project
|
||||
project_id: 6553b53c-bf14-49e3-a3de-1ee2f3533d51
|
||||
workspace_type: development
|
||||
usage_profile_id: null
|
||||
preference_context: development
|
||||
document_type: architecture
|
||||
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: openai/gpt-oss-120b
|
||||
source_count: 13
|
||||
source_revisions: {}
|
||||
source_dispositions:
|
||||
processed: 13
|
||||
unchanged: 0
|
||||
unsupported: 0
|
||||
skipped: 0
|
||||
cited_source_ids:
|
||||
- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
|
||||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||||
- global_guidance_memory:1194be51-ee29-47e1-8957-ec2888007db6
|
||||
job_cited_source_ids:
|
||||
- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
|
||||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||||
- global_guidance_memory:1194be51-ee29-47e1-8957-ec2888007db6
|
||||
conflicts: []
|
||||
supersedes: []
|
||||
preferences: []
|
||||
source_cursor: 207
|
||||
source_hash: 5a2bf7e4aa8a90513e133f70e1737cdaf99fddd9888166c7645ba4700934109c
|
||||
prompt_version: 2026-08-12.3
|
||||
schema_version: '3'
|
||||
curation_job_id: 831de31c-3ff7-4cb5-81ed-55b900461a33
|
||||
created_at: '2026-08-31T03:10:05.582276+00:00'
|
||||
updated_at: '2026-08-31T03:10:05.583206+00:00'
|
||||
tags:
|
||||
- development
|
||||
- architecture
|
||||
---
|
||||
|
||||
## 总体架构
|
||||
|
||||
1. **硬件/宿主平台**
|
||||
- 主机操作系统：Windows 10/11。
|
||||
- 虚拟化层：WSL2（Linux 子系统）+ Docker Desktop。
|
||||
- 网络：容器通过 `host.docker.internal` 访问宿主服务；必要时使用网关 `172.17.0.1`。
|
||||
|
||||
2. **容器化服务**
|
||||
- 业务服务（如 FastAPI、数据库等）运行在 Docker 容器内，端口统一映射到 `0.0.0.0` 以供宿主和外部访问。
|
||||
- 代理层：Docker Desktop 代理手动配置为 `http://127.0.0.1:7897`（支持 HTTP 与 HTTPS），确保所有容器的外网请求走本地代理。
|
||||
|
||||
3. **记忆与版本管理**
|
||||
- **MemRelay**：统一的记忆持久化后端，负责 `aidocs/project_context.md` 中的笔记存取。
|
||||
- **Git**：本地 Git 仓库仅用于提交代码；`aidocs/` 目录已加入 `.gitignore`，记忆文件不随代码推送。
|
||||
- 提交信息格式：`type: 中文一句话描述`（`type` 为 `feat/fix/refactor/style/docs/chore/revert`）。
|
||||
|
||||
4. **安全与凭证**
|
||||
- 所有登录、SSH、数据库、API 调用前先查询 **Vaultwarden**；唯一匹配时自动使用。
|
||||
- 新增或修改的密码、Token、API‑Key、TOTP 种子立即写入密码库，记忆中仅记录名称、用途、使用方式。
|
||||
|
||||
5. **开发原则**
|
||||
- **KISS 与 YAGNI**：实现最简且正确，复用已有框架与工具，避免投机性依赖。
|
||||
- **AI 与 Git 自动化**：默认关闭，除非显式启用。
|
||||
|
||||
6. **常见技术约束**
|
||||
- **FastAPI**：避免在 `async` 接口中使用阻塞 I/O。
|
||||
- **PowerShell**：发送 JSON 时使用临时文件并 `--data-binary @file`。
|
||||
- **Docker Exec**：长连接需取消默认 3 秒超时。
|
||||
|
||||
**标签**: ["development", "architecture"]
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
---
|
||||
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: openai/gpt-oss-120b
|
||||
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: 831de31c-3ff7-4cb5-81ed-55b900461a33
|
||||
created_at: '2026-08-31T03:10:15.092752+00:00'
|
||||
updated_at: '2026-08-31T03:10:15.093384+00:00'
|
||||
tags:
|
||||
- maintenance
|
||||
- development
|
||||
---
|
||||
|
||||
# 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"]
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: HanteleWorkTime 部署指南
|
||||
type: curated
|
||||
permalink: main/projects/6553b53c-bf14-49e3-a3de-1ee2f3533d51/curated/development/hantele-work-time-部署指南
|
||||
stable_id: 5d0e9587-c39b-4f66-b84a-9259d3a22a05
|
||||
scope: project
|
||||
project_id: 6553b53c-bf14-49e3-a3de-1ee2f3533d51
|
||||
workspace_type: development
|
||||
usage_profile_id: null
|
||||
preference_context: development
|
||||
document_type: deployment
|
||||
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: openai/gpt-oss-120b
|
||||
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: 831de31c-3ff7-4cb5-81ed-55b900461a33
|
||||
created_at: '2026-08-31T03:10:12.978059+00:00'
|
||||
updated_at: '2026-08-31T03:10:12.978756+00:00'
|
||||
tags:
|
||||
- deployment
|
||||
- development
|
||||
---
|
||||
|
||||
# HanteleWorkTime 部署指南
|
||||
|
||||
本文档面向 **HanteleWorkTime** 项目（工作区类型：development），提供当前可执行的部署步骤与注意事项。
|
||||
|
||||
## 1. 环境要求
|
||||
- 操作系统：Windows（使用 **WSL2 + Docker Desktop**） [来源: `global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e`]
|
||||
- Docker 代理：手动模式，HTTP 与 HTTPS 均指向 `http://127.0.0.1:7897`，重启 Docker 后验证 `docker pull` 正常工作 [来源: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`]
|
||||
- 网络访问：容器内部访问宿主代理使用 `host.docker.internal:7897`，如需直接访问宿主 IP 采用 `172.17.0.1`（桥接网络） [来源: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`]
|
||||
|
||||
## 2. 基本部署原则
|
||||
- **KISS 与 YAGNI**：只实现最简且正确的功能，不为猜测的未来需求添加依赖或抽象层 [来源: `global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5`]
|
||||
- **复用已有框架**：优先使用项目已有的服务、约定和工具，避免重复实现 [同上]
|
||||
|
||||
## 3. AI 与 Git 同步（可选）
|
||||
- 默认 **关闭** AI 驱动的记忆同步与 Git 集成；系统在未显式开启时不会尝试加载模型、创建 `.git` 目录或进行自动 push [来源: `global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d`]
|
||||
- 如需启用，请在部署脚本中显式配置相应的 MemRelay 插件并确认 `.git` 目录已创建 [来源: `global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d`]
|
||||
|
||||
## 4. 凭证与安全
|
||||
- 所有登录、SSH、数据库或 API 调用 **前** 必须在 Vaultwarden 中搜索对应条目；若唯一匹配则自动使用，否则提示人工选择 [来源: `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`]
|
||||
- 新增或修改的密码、Token、API‑Key、TOTP 种子 **立即** 写入密码库；记忆中仅记录条目名称、用途与使用方式，绝不保存密文 [同上]
|
||||
- 项目当前使用的基础设施条目包括 BDYG18Pro、OpenWrt、MySQL、MemRelay、Gitea OAuth、FRP Token 与公网 FRPS 服务器 [同上]
|
||||
|
||||
## 5. 部署步骤概览
|
||||
1. **准备环境**：确认 Windows + WSL2 + Docker Desktop 已安装并符合上文的代理与网络设置。
|
||||
2. **拉取代码**：在本地工作区执行 `git clone <repo>`（仅克隆代码，不会自动创建 `.git` 除非显式请求）。
|
||||
3. **配置凭证**：运行部署脚本前，确保所有必需的凭证已在 Vaultwarden 中存在且唯一。
|
||||
4. **构建容器**：使用 `docker compose build`，期间 Docker 将通过 `host.docker.internal:7897` 访问外部代理。
|
||||
5. **启动服务**：`docker compose up -d`，检查容器日志确保无凭证加载错误。
|
||||
6. **验证**：访问服务的 UI（如有），确认页面顶部标题在滚动时保持可见，表单布局符合 **“标题在左、控件在右”** 的紧凑横向规范 [来源: `global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5`]
|
||||
7. **记录部署**：在 `aidocs/project_context.md` 追加部署记录（时间戳、操作、验证结果），该文件不被提交至 Git [来源: `global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e`]
|
||||
|
||||
## 6. 常见问题
|
||||
- **Docker 拉取超时**：确认代理已正确配置并在系统代理中开启。若仍失败，检查 `settings-store.json` 中 `ProxyHTTPMode=manual` 是否生效。 [来源: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`]
|
||||
- **AI 模型意外加载**：检查环境变量 `MEMRELAY_AI_ENABLED` 是否被误设为 `true`，否则系统会尝试加载默认模型并报错。 [来源: `global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d`]
|
||||
- **凭证未自动使用**：确保 Vaultwarden 中的条目名称唯一；多个匹配会导致系统提示手动选择。 [来源: `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`]
|
||||
|
||||
---
|
||||
|
||||
**标签**: ["deployment","development"]
|
||||
Reference in New Issue
Block a user