使用Blossom与Codex建立局域网知识库
使用Blossom与Codex建立局域网知识库
本知识库的主要目的是使用Blossom笔记软件进行笔记编写，并且在需要在知识库进行信息检索和总结的时候可以通过Codex直接接入，实现“本地知识库+云端AI能力”的结合。
基础部署
Blossom部署
本例的部署环境为龙芯3A6000 openEuler-24.03-LTS。如果使用与本例相同的方法，理论上支持JAVA21的指令集架构都可以部署，包括常见的amd64、aarch64、rv64等。
数据库和文件准备
首先，在MariaDB中创建一个名为blossom的数据库和同名的用户：
CREATE DATABASE blossom CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'blossom'@'%' IDENTIFIED BY 'blossom';
GRANT ALL PRIVILEGES ON *.* TO 'blossom'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;
然后下载.jar安装包：
wget https://github.com/blossom-editor/blossom/releases/download/v1.17.1/backend-blossom.jar
启动验证
启动这个.jar文件：
java -jar ./backend-blossom.jar \
--server.port=9999 \
--project.iaas.blos.default-path="/mnt/data_0/blossom/img" \
--spring.datasource.url="jdbc:mysql://127.0.0.1:3306/blossom?useUnicode=true&characterEncoding=utf8&allowPublicKeyRetrieval=true&allowMultiQueries=true&useSSL=false&&serverTimezone=GMT%2B8" \
--spring.datasource.username=blossom \
--spring.datasource.password=blossom
以上字段的含义分别为：
| 字段 | 含义 |
|---|---|
| --server.port | 端口号 |
| --project.iaas.blos.default-path | 图片储存的位置 |
| --spring.datasource.url | MariaDB数据库的URL，如果需要更改的话只改地址和端口就行了 |
| --spring.datasource.username | MariaDB数据库的用户名 |
| --spring.datasource.password | MariaDB数据库的密码 |
这样就可以完成启动验证了，相当于服务器已经启动了。如果需要访问的话，还需要设置防火墙放行9999端口：
sudo firewall-cmd --permanent --add-port=9999/tcp
sudo firewall-cmd --reload
然后再客户端中填入：
| 字段 | 内容 |
|---|---|
| URL | http:// |
| 用户名 | blos |
| 密码 | blos |
部署系统服务
[!WARNING]
使用<Blossom DIR>代指.jar文件的存放目录和各种文件的存放目录
首先进入到<Blossom DIR>并且创建startup.sh：
cd <Blossom DIR>
vim startup.sh`
填入内容：
java -jar ./backend-blossom.jar \
--server.port=9999 \
--project.iaas.blos.default-path="/mnt/data_0/blossom/img" \
--spring.datasource.url="jdbc:mysql://127.0.0.1:3306/blossom?useUnicode=true&characterEncoding=utf8&allowPublicKeyRetrieval=true&allowMultiQueries=true&useSSL=false&&serverTimezone=GMT%2B8" \
--spring.datasource.username=blossom \
--spring.datasource.password=blossom
然后编辑系统服务文件/etc/systemd/system/blossom.service，并且填入：
[Unit]
Description=Blossom Server
After=network.target mariadb.service
Wants=mariadb.service
[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/mnt/data_0/blossom
ExecStart=bash /mnt/data_0/blossom/startup.sh
ExecStop=/bin/kill -15 $MAINPID
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=blossom
[Install]
WantedBy=multi-user.target
然后就是标准systemd新服务启动流程：
systemctl daemon-reload
systemctl enable blossom --new
最后查看服务状态：
systemctl status blossom
Codex安装
详情参考
Codex安装教程
完成Codex安装和账号登录等内容
Blossom
Blossom进行正常登录即可。网页和客户端都可以。
Codex的Blossom技能
Codex的Blossom技能目录结构如下：
/home/ubuntu/.codex/skills/blossom/
├── package-metadata.json
├── README.md
├── references
│ ├── api-contract.md
│ ├── compatibility.md
│ └── data-model.md
├── scripts
│ ├── blossom_client.py
│ ├── blossom_cli.py
│ ├── __init__.py
│ ├── live_smoke.py
│ ├── live_snapshot_smoke.py
│ ├── normalizer.py
│ ├── __pycache__
│ │ ├── blossom_client.cpython-312.pyc
│ │ ├── normalizer.cpython-312.pyc
│ │ └── snapshot.cpython-312.pyc
│ └── snapshot.py
├── SKILL.md
├── tests
│ ├── fixtures
│ │ └── contract_samples.json
│ ├── test_auth.py
│ ├── test_compatibility.py
│ ├── test_contract.py
│ ├── test_normalization.py
│ ├── test_package.py
│ ├── test_resources.py
│ ├── test_security.py
│ └── test_snapshot.py
└── VERSION
6 directories, 26 files
该技能主要功能是给Codex提供Blossom的操作接口和登录规范，其中的Python代码文件是http接口，Codex可以通过这些Python代码实现对于Blossom服务器的操作，包括抓取目录、取文件内容等。该技能已经过充分测试。
Git仓库
Git仓库主要用于在该仓库目录下打开Codex，并且直接询问Codex时可以有限在Blossom文档里面寻找信息，相当于依靠本地知识库进行信息提取与总结。
Git仓库结构如下（代码块前的\要进行删除）：
./
├── AGENTS.md
├── note
│ ├── 2026-09-17-170154-查询-VMware压缩硬盘.md
│ ├── 2026-09-17-170745-查询-龙芯平台编译安装QEMU.md
│ └── README.md
├── outline
│ ├── 2026-09-17-170112-查询-VMware压缩硬盘.md
│ ├── 2026-09-17-170535-查询-龙芯平台编译安装QEMU.md
│ └── README.md
└── README.md
3 directories, 8 files
AGENTS.md是仓库的规则文件，Codex在第一次对话的时候必定会阅读此文件，并且按照此规则文件进行下一步工作。
note目录是每一次提问的笔记记录，由note/README.md文件建立索引；outline目录是每一次启动Codex读取到的目录大纲，用来辅助记录文章目录和提问的问题（可以看到两个目录中都有测试遗留的记录文件）。
AGENTS.md文档内容如下：
# Blossom 知识库协作规则
本目录是 Blossom 知识库的本地协作入口。所有涉及 Blossom 服务的操作，都必须遵守以下规则。
## 连接配置
以下是本知识库的运行时连接信息：
- 服务器地址：xxx
- 用户名：xxx
- 密码：xxx
- 调用 Base URL：`http://xxx`
本文件含有敏感凭据。不要将其复制到 `README.md`、`note/`、命令输出、日志、提交信息或对话回复中；本文件应保持仅当前用户可读。
## 登录与令牌生命周期
1. 每开启一个新的上下文聊天，先读取本文件，并使用运行时注入的用户名和密码重新登录；不得复用其他上下文的令牌。
2. Blossom 请求使用随附 Blossom 技能提供的只读客户端，登录流程为 `POST /login`，随后校验 `/check`。
3. 令牌只能存在于当前运行中的客户端进程内存中。不得写入文件、环境快照、Shell 历史、日志、笔记、压缩摘要或对话回复，也不得打印令牌。
4. 上下文压缩前后只保留不含秘密的会话状态（例如“需要重新登录”或“活动客户端仍在运行”）。如果持有令牌的客户端进程仍然存活，则继续使用其内存中的令牌；如果进程不可用或令牌失效，必须在压缩恢复后的第一个 Blossom 请求前重新登录。
5. 出现 `AUTH-40101` 或 `AUTH-40102` 时，清除当前内存会话并停止静默重试，重新进行一次运行时登录；不要无限次重试密码。
建议通过 `BLOSSOM_USERNAME` 和 `BLOSSOM_PASSWORD` 注入运行时凭据，不要把密码作为命令行参数传递。登录、读取和清理会话应由 Blossom 技能的 `scripts/blossom_cli.py` 完成；该客户端会在进程结束时清理令牌。
## 知识库查询优先规则
- 在本知识库目录下提出的问题，首先搜索知识库。
- 如果知识库中没有相关内容，暂停继续处理，先向用户汇报未找到相关内容，并询问是否需要进行互联网搜索；未经用户确认，不进行互联网搜索。
## Codex 运行大纲与索引规则
- 每次运行 Codex 时，在处理本次运行的第一个提问前，登录blossom并且获取到全部文章的大纲，先在 `outline/` 目录下创建一份新的大纲记录文件记录获取到的大纲，然后更新 `outline/README.md` 的索引。
- 大纲记录文件名沿用 `note/` 目录的规则：`YYYY-MM-DD-HHmmss-类别-标题.md`；开始时记录本次运行的目的和计划，完成后补充结果和后续事项。
- `outline/README.md` 是 `outline/` 目录的独立索引；新增或更新大纲记录时同步更新索引。
- 每次更新`outline/README.md`时，如果发现实际文件信息与`outline/README.md`不符，则使用实际文件信息更新`outline/README.md`。
## 本地记录规则
- 使用记录统一存放在 `note/`。`note/README.md` 是 `note/` 目录的独立索引；新增使用、配置变更、查询结果或故障记录时同步更新索引。
- 文件名统一为：`YYYY-MM-DD-HHmmss-类别-标题.md`。
- 时间采用 `Asia/Shanghai`；类别使用简短中文词，例如 `配置`、`登录`、`查询`、`同步`、`故障`、`整理`。
- 标题使用简短、可读的文字；文件名中避免空格和路径分隔符。
- 记录内容不得包含密码、令牌、Authorization 请求头、完整 Cookie 或其他秘密。
- 每次新的使用、配置变更、查询结果或故障处理都新建记录，不覆盖既有记录。
- 每次更新`note/README.md`时，如果发现实际文件信息与`note/README.md`不符，则使用实际文件信息更新`note/README.md`。
推荐的记录结构：
\```markdown
# 标题
- 时间：YYYY-MM-DD HH:mm:ss
- 类别：类别
- 目的：
- 操作：
- 结果：
- 后续：
\```
## 上下文启动清单
- 阅读 `AGENTS.md` 和 `README.md`。
- 确认当前上下文尚未建立 Blossom 会话。
- 通过运行时凭据完成一次新登录和 `/check` 校验。
- 完成工作后，不在本地记录令牌；按客户端流程清理会话。
README.md文档内容如下（代码块前的\要进行删除）：
# Blossom 知识库
这是 Blossom 私有知识库的本地协作目录，保存连接约定、上下文操作规则和使用记录。远端 Blossom 服务是内容来源，本目录主要用于可追溯地记录本地协作过程。
## 目录结构
\```text
.
├── AGENTS.md # 连接配置、登录和协作规则（含敏感凭据）
├── README.md # 本说明
├── outline/ # 每次 Codex 运行的大纲记录
│ ├── README.md
│ └── YYYY-MM-DD-HHmmss-类别-标题.md
└── note/ # 使用记录
├── README.md
└── YYYY-MM-DD-HHmmss-类别-标题.md
\```
## 开始使用
每个新的上下文聊天都必须先阅读 `AGENTS.md`，再使用 Blossom 技能的只读客户端重新登录。凭据只在运行时注入 `BLOSSOM_USERNAME` 和 `BLOSSOM_PASSWORD`；令牌只保留在活动客户端的内存中，不写入任何文件、日志或上下文压缩摘要。
服务器地址、用户名和密码仅记录在 `AGENTS.md`。上下文压缩恢复后，若原活动客户端仍存活则继续使用其内存会话；否则先重新登录，再发起任何 Blossom 请求。
## 大纲记录
每次运行 Codex 时，在处理第一个提问前先更新 `outline/README.md`，并在 `outline/` 创建新的大纲记录。大纲记录的命名规则与 `note/` 相同，详细索引见 [`outline/README.md`](outline/README.md)。
## 使用记录
所有使用记录放入 `note/`，并由 [`note/README.md`](note/README.md) 统一索引。文件名格式为：
\```text
YYYY-MM-DD-HHmmss-类别-标题.md
\```
示例：
\```text
2026-09-17-163831-配置-知识库初始化.md
\```
时间使用 `Asia/Shanghai`。记录应包含时间、类别、目的、操作、结果和后续；禁止写入密码、令牌、Authorization 请求头和完整 Cookie。
## 安全边界
`AGENTS.md` 含有明文连接凭据，已按本地私密配置处理。不要把它复制到笔记、公开文档、日志或对话中。当前知识库初始化只建立本地协作体系并验证登录，不执行 Blossom 远端内容修改。
使用方法
直接在Git仓库的目录下打开终端，然后启动Codex即可。启动之后可以在Codex中直接进行提问，它会优先根据Blossom的文档内容进行回答。如果知识库中没有相应的信息，则会先询问用户是否从互联网搜集资料。如果用户允许，则从互联网搜集相关资料并且整合，然后进行回答。
浙公网安备 33010602011771号