暂存

scriptdoc/README.md

@@ -0,0 +1,35 @@
+# 脚本文档总览
+
+当前 `scriptdoc/` 中的文档按脚本拆分：
+
+- [setup_database.md](/www/proofdb/scriptdoc/setup_database.md): PostgreSQL 结构初始化与升级
+- [setup_admin_users.md](/www/proofdb/scriptdoc/setup_admin_users.md): 管理员用户表与首个管理员账号初始化
+- [setup_opensearch.md](/www/proofdb/scriptdoc/setup_opensearch.md): OpenSearch 索引初始化
+- [reindex_opensearch.md](/www/proofdb/scriptdoc/reindex_opensearch.md): OpenSearch 重建索引与回灌
+- [backfill_archive_content.md](/www/proofdb/scriptdoc/backfill_archive_content.md): 历史 archive `content` 正文字段回填
+
+## 当前运维脚本
+
+```text
+scripts/setup_database.php
+scripts/setup_admin_users.php
+scripts/setup_opensearch.php
+scripts/reindex_opensearch.php
+scripts/backfill_archive_content.php
+```
+
+## 推荐顺序
+
+首次初始化或较完整的修复操作，通常按下面顺序执行：
+
+```bash
+php scripts/setup_database.php
+php scripts/setup_opensearch.php
+php scripts/reindex_opensearch.php
+```
+
+如果本地 OpenSearch 使用 HTTPS 且证书为自签名，可在相关脚本前临时加：
+
+```bash
+OPENSEARCH_SSL_VERIFY=false
+```

scriptdoc/backfill_archive_content.md

@@ -0,0 +1,76 @@
+# Archive Content 回填脚本
+
+## 脚本路径
+
+```text
+scripts/backfill_archive_content.php
+```
+
+## 脚本作用
+
+回填历史 `archives.content` 字段。
+
+这个脚本主要用于修复旧数据中 `content` 为空的问题。它会按下面顺序尝试生成 `content`：
+
+1. 如果 archive 有 `raw`，就按当前导入规则把原始 Markdown 规范化成正文文本。
+2. 如果 `raw` 为空，就按 `chunk_index` 顺序拼接现有 chunk 的 `text` 作为回退正文。
+
+脚本不会伪造 `raw`。如果历史数据里 `raw` 丢了，脚本只会尽力补 `content`。
+
+## 运行前提
+
+- 当前环境中的 PostgreSQL 配置可用。
+- 项目依赖已安装完成。
+- 从项目根目录执行命令。
+
+## 运行命令
+
+默认只处理 `content` 为空的 archive：
+
+```bash
+php scripts/backfill_archive_content.php
+```
+
+只处理一个 archive：
+
+```bash
+php scripts/backfill_archive_content.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY
+```
+
+强制重算，即使 `content` 已经有值：
+
+```bash
+php scripts/backfill_archive_content.php --force
+```
+
+只预览，不写数据库：
+
+```bash
+php scripts/backfill_archive_content.php --dry-run
+```
+
+## 成功输出示例
+
+```text
+[updated] 01KQHVREB6XPYF604RVZAP9NNY source=chunks content_length=6375
+Archive content backfill completed.
+Archive filter: auto
+Force mode: no
+Dry run: no
+Scanned: 1
+Updated: 1
+From raw: 0
+From chunks: 1
+Skipped: 0
+```
+
+## 适用场景
+
+- 修复旧版本导入留下的 `archives.content` 为空问题。
+- 导入逻辑更新后，希望重算归一化正文。
+- 为后续 AI / RAG / archive 级读取补齐正文字段。
+
+## 重要限制
+
+- 如果历史数据既没有 `raw`，也没有 chunks，脚本会跳过该 archive。
+- 用 chunks 回填时，得到的是拼接后的正文文本，不会恢复原始 Markdown 结构。

scriptdoc/reindex_opensearch.md

@@ -0,0 +1,93 @@
+# OpenSearch 重建索引脚本
+
+## 脚本路径
+
+```text
+scripts/reindex_opensearch.php
+```
+
+## 脚本作用
+
+根据 PostgreSQL 中已经完成向量化的 chunk，重新构建 OpenSearch 中的 `proofdb_chunks` 索引内容，并刷新每条 chunk 的派生搜索字段。
+
+脚本会做这些事：
+
+1. 确保 OpenSearch 索引存在。
+2. 把已向量化 chunk 的 `search_index_status` 重置为待索引。
+3. 按 archive 批量重新投递索引任务。
+4. 调用现有 OpenSearch indexing handler 批量写入 chunk 文档。
+5. 输出重建统计结果。
+
+## 运行前提
+
+- PostgreSQL 可连接。
+- OpenSearch 可连接。
+- 目标 chunk 的 `embedding_status` 已经是 `embedded`。
+- 项目依赖已安装完成。
+- 从项目根目录执行命令。
+
+如果本地 OpenSearch 使用 HTTPS 且证书是自签名：
+
+```bash
+OPENSEARCH_SSL_VERIFY=false php scripts/reindex_opensearch.php
+```
+
+## 运行命令
+
+全量重建：
+
+```bash
+php scripts/reindex_opensearch.php
+```
+
+只重建一个 archive：
+
+```bash
+php scripts/reindex_opensearch.php --archive_uid=01KQHVREB6XPYF604RVZAP9NNY
+```
+
+## 成功输出示例
+
+```text
+OpenSearch reindex completed.
+Index: proofdb_chunks
+Archive filter: (all embedded archives)
+Reset chunks: 14
+Indexed archives: 1
+Indexed chunk rows now marked indexed: 14
+Archives: 01KQHVREB6XPYF604RVZAP9NNY
+```
+
+## 适用场景
+
+- `proofdb_chunks` 被误删后恢复。
+- 数据库里 `search_index_status=3`，但 OpenSearch 中没有对应文档。
+- 索引 mapping 重建后，需要把已经 embedding 完成的数据重新灌回 OpenSearch。
+- archive 的 `summary`、`title`、`tags` 等搜索元数据有更新后，需要刷新到 OpenSearch。
+
+## 重要限制
+
+这个脚本只处理已经向量化完成的 chunk。
+
+它不会：
+
+- 重新生成 embedding。
+- 修复 embedding 失败的数据。
+- 修复 PostgreSQL 中缺失的 archive 或 chunk。
+
+## 推荐用法
+
+如果 OpenSearch 整个索引丢了，通常按下面顺序执行：
+
+```bash
+php scripts/setup_opensearch.php
+php scripts/reindex_opensearch.php
+```
+
+如果数据库 schema 也有变动，则先补数据库：
+
+```bash
+php scripts/setup_database.php
+php scripts/setup_opensearch.php
+php scripts/reindex_opensearch.php
+```

scriptdoc/setup_admin_users.md

@@ -0,0 +1,56 @@
+# 管理员用户初始化脚本
+
+## 脚本路径
+
+```text
+scripts/setup_admin_users.php
+```
+
+## 脚本作用
+
+初始化管理员登录使用的 `admin_users` 表，并写入一个管理员账号。
+
+当前版本会确保：
+
+- `admin_users` 表存在。
+- `username` 唯一索引存在。
+- `updated_time` 自动更新时间 trigger 存在。
+- 指定用户名会被创建；如果已存在，则会更新显示名和密码哈希。
+
+## 运行前提
+
+- 当前环境中的 PostgreSQL 配置可用。
+- 项目依赖已安装完成。
+- 从项目根目录执行命令。
+
+## 运行命令
+
+```bash
+php scripts/setup_admin_users.php --username=admin --password='your-password' --display_name='Proof DB Admin'
+```
+
+其中：
+
+- `--username` 必填
+- `--password` 必填
+- `--display_name` 选填
+
+## 成功输出示例
+
+```text
+Admin users table initialized.
+Seeded username: admin
+Display name: Proof DB Admin
+```
+
+## 适用场景
+
+- 首次启用管理员登录。
+- 需要创建第一个管理员用户。
+- 需要重置已有管理员的密码。
+
+## 重要说明
+
+- 这个脚本不会输出明文密码。
+- 再次执行同一用户名时，会更新密码哈希。
+- 建议在安全环境下执行，不要把明文密码写进仓库文件。

scriptdoc/setup_database.md

@@ -0,0 +1,51 @@
+# 数据库初始化脚本
+
+## 脚本路径
+
+```text
+scripts/setup_database.php
+```
+
+## 脚本作用
+
+初始化或升级 Proof DB 使用的 PostgreSQL 结构。
+
+当前版本会确保：
+
+- `archives` 表存在。
+- `chunks` 表存在。
+- 档案与 chunk 的常用索引存在。
+- embedding / search index 相关状态字段存在。
+- `updated_time` 自动更新时间触发器存在。
+
+## 运行前提
+
+- 当前环境中的 PostgreSQL 配置可用。
+- 项目依赖已安装完成。
+- 从项目根目录执行命令。
+
+## 运行命令
+
+```bash
+php scripts/setup_database.php
+```
+
+## 成功输出示例
+
+```text
+Database connection ok: postgre
+Tables initialized: archives, chunks
+```
+
+## 适用场景
+
+- 首次部署环境。
+- 拉取了数据库结构相关代码后同步 schema。
+- 新增了状态字段、索引或 trigger 后补齐现有数据库。
+
+## 常见失败信号
+
+- `PDOException`
+  说明数据库地址、账号密码、网络或 DNS 有问题。
+- SQL 执行错误
+  说明权限不足，或者现有 schema 与代码预期不一致。

scriptdoc/setup_opensearch.md

@@ -0,0 +1,59 @@
+# OpenSearch 索引初始化脚本
+
+## 脚本路径
+
+```text
+scripts/setup_opensearch.php
+```
+
+## 脚本作用
+
+创建或确认 Proof DB 使用的 OpenSearch chunk 索引，并同步缺失的增量 mapping 字段。
+
+当前版本会确保：
+
+- `proofdb_chunks` 索引存在。
+- BM25 全文字段 mapping 已建立。
+- 已存在索引上的缺失字段 mapping 会被补齐，例如后续新增的 `summary`。
+- `embedding` 字段为 `knn_vector`。
+- 向量维度与当前配置一致。
+
+## 运行前提
+
+- OpenSearch 服务已经启动。
+- 当前环境中的 OpenSearch 配置可用。
+- 项目依赖已安装完成。
+- 从项目根目录执行命令。
+
+如果本地 OpenSearch 使用 HTTPS 且证书是自签名：
+
+```bash
+OPENSEARCH_SSL_VERIFY=false php scripts/setup_opensearch.php
+```
+
+## 运行命令
+
+```bash
+php scripts/setup_opensearch.php
+```
+
+## 成功输出示例
+
+```text
+OpenSearch chunk index initialized: proofdb_chunks
+Vector dimensions: 2048
+```
+
+## 适用场景
+
+- OpenSearch 首次初始化。
+- `proofdb_chunks` 被删除后重建。
+- 增加了新的文档字段，例如 `summary`。
+- 调整了索引 mapping 或向量维度后重新准备索引。
+
+## 常见失败信号
+
+- `NoNodesAvailableException`
+  说明 host、协议、端口、SSL 校验或服务状态不对。
+- 鉴权失败
+  说明 `OPENSEARCH_USERNAME` / `OPENSEARCH_PASSWORD` 不正确。