This repository has no description

Fork 0

TypeScript 35%

CSS 24%

Rust 24%

JavaScript 17%

PLpgSQL <1%

Shell <1%

Dockerfile <1%

HTML <1%

<1%

56 1 0

Branches 1

master · 1d ago Default

README.md

Odre #

Odre — приватная персональная образовательная платформа для заметок, курсов, задач, материалов и пространственной работы. Система рассчитана на одного владельца и доступ с его устройств через браузер.

Возможности #

карточки и посты с визуальным блочным редактором;
код, изображения, ссылки, task lists, LaTeX и Spatial Workspace;
autosave, optimistic concurrency, immutable revisions и восстановление;
теги, aliases, backlinks и Knowledge Graph;
приватные annotation threads;
Problems, Library, Learning, Whiteboards и Study Workspace;
статьи Markdown с формулами, Mermaid и упражнениями, непрерывное чтение PDF;
выделения, учебные заметки, интервальное повторение и поиск по материалам;
генерация и точечная правка статей с потоком ответа, выбором модели и историей;
настройки AI providers и scoped agent API;
загрузка assets и полный JSON export/import.

Стек #

Backend: Rust 2024, Axum, SQLx, PostgreSQL 17 и Tokio.

Frontend: TypeScript, React 18, Vite, TanStack Query, Tiptap, Excalidraw и React Flow.

Инфраструктура: Docker Compose и Nginx. Снаружи публикуется только web-вход Odre; API и PostgreSQL остаются во внутренней Docker-сети.

Browser ──> Odre Nginx ──> Odre API ──> PostgreSQL
                              │
                              └──────────> private asset volume

Локальный запуск #

Требуются Colima или другой Docker Engine с Compose plugin (docker compose).

colima start
docker compose up -d --build

Odre доступен по адресу http://localhost:5173.

Обычный Knowledge Graph загружает только сохранённые заметки и при пустом хранилище показывает empty state. Плотный демонстрационный граф для визуальной регрессии доступен только явно через ?graphFixture=dense.

Odre не запрашивает логин, пароль или сессионную cookie. Контроль доступа осуществляется на уровне VPS и Tailscale: не публикуйте порт Odre в открытый интернет и разрешайте его только нужным tailnet-устройствам.

Перед постоянным развёртыванием задайте пароль PostgreSQL и секрет шифрования ключей провайдеров:

POSTGRES_PASSWORD=<длинный случайный пароль>
API_KEY_ENCRYPTION_SECRET=<длинный случайный секрет>

POSTGRES_PASSWORD нужен production Compose для базы и API. Оба значения хранятся только в серверном .env и не должны попадать в Git.

Секрет шифрования нельзя менять после сохранения provider API keys без предварительной миграции.

Полезные команды:

docker compose ps
docker compose logs -f platform-api platform-web
docker compose stop
docker compose down
curl --fail http://localhost:5173/health

docker compose down сохраняет именованные volumes. Не используйте docker compose down -v, если данные должны сохраниться.

Разработка из исходников #

Запустите PostgreSQL с loopback-портом:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d platform-db

Затем можно запускать компоненты отдельно:

cargo run -p platform-api
pnpm install --frozen-lockfile
pnpm dev:platform

В этом режиме Vite работает на 5173, а Rust API — на 4100.

Базовые проверки:

cargo check
cargo test
pnpm typecheck
pnpm build:web
docker compose build

Backup и restore #

Backup содержит PostgreSQL dump, приватный asset volume и шаблон переменных окружения без реальных секретов.

bash scripts/backup.sh
bash scripts/restore.sh backups/<backup-directory>

Объединение с прежним Odre #

Постоянная база объединённого сервиса — PostgreSQL. Прежнее приложение Odre на SQLite остаётся источником совместимого формата импорта; отдельный Node-сервер в новой системе не требуется. Статьи находятся в Notes, книги и внешние ресурсы — в Library. Learning использует те же заметки. Существующие структурированные уроки продолжают открываться в редакторе; новые уроки ссылаются на общую заметку с единой историей.

Настройки провайдеров и разговоры общие. Ответ модели сам по себе не изменяет заметку или урок. Генерация сохраняет предложение, применение проверяет версию и сохраняет историю. Codex app-server пока не используется.

В Settings можно импортировать старый Odre backup ZIP. ZIP переносит учебные записи как новые материалы; ключи провайдеров надо настроить отдельно. Новый полный экспорт JSON включает все области, разговоры, состояние чтения и относительные файлы статей. Старый forge-platform-export также принимается. Операционный backup по-прежнему содержит PostgreSQL dump и весь asset volume.

Для внешних агентов см. AGENT_GUIDE.md, для развёртывания объединения — docs/merge-deployment.md. Результаты приёмки — docs/merge-qa.md.

Agent API #

Запросы идут через Odre:

curl http://localhost:5173/agent/v1/capabilities

Agent API также не использует отдельный токен: его доступ ограничивается тем же VPS и Tailscale-контуром.

Структура репозитория #

apps/platform-api/   приватный Rust API
apps/platform-web/   Odre React application
migrations/platform/ PostgreSQL migrations
context/              продуктовая спецификация и долговечный контекст
scripts/              backup и restore

Production-развёртывание #

Production работает на VPS в /opt/services/myspace2 из ветки master в Tangled. Историческое имя Compose-проекта — forge; PostgreSQL и assets хранятся в именованных Docker volumes. Odre доступен только через Tailscale: https://olfrenn.tail641a4e.ts.net:8443.

После локальной проверки изменения закоммитьте его и отправьте в Tangled, затем обновите VPS:

ssh root@100.95.59.50
z myspace2
git pull --ff-only
docker compose -f docker-compose.yml -f docker-compose.production.yml up -d --build
docker compose -f docker-compose.yml -f docker-compose.production.yml ps

POSTGRES_PASSWORD и API_KEY_ENCRYPTION_SECRET хранятся только в .env на VPS и не коммитятся. Перед рискованными миграциями или изменениями данных создавайте backup командой bash scripts/backup.sh.

Clone this repository