Самостоятельно развёртываемое приложение с открытым исходным кодом и карточками для интервального повторения
Да, Flashcards можно развернуть на собственной инфраструктуре. Весь код приложения и инфраструктуры открыт по лицензии MIT. Сервисы можно запустить локально для разработки или развернуть в AWS описанный в документации рабочий стек из репозитория. Если вы не хотите управлять инфраструктурой, по-прежнему доступно облачное приложение.
Что можно развернуть самостоятельно
В репозитории находятся сервисы и инфраструктура основной системы Flashcards:
- веб-приложение и приложение для администраторов
- API бэкенда и сервис входа без пароля
- схема PostgreSQL, миграции, синхронизация и планирование повторений на основе FSRS
- сервер MCP и Agent API для программных клиентов
- стек AWS CDK для сети, базы данных, аутентификации, API, статического веб-хостинга, секретов, резервного копирования, мониторинга и CI/CD
В репозитории также есть нативные клиенты для iOS и Android. Эти приложения собираются отдельно: развёртывание стека AWS не публикует за вас собственные версии в App Store или Google Play.
Серверный стек можно запустить двумя поддерживаемыми способами:
- Локальная разработка: Docker Compose запускает PostgreSQL и задачу миграции. Скрипты репозитория запускают на основной системе серверы разработки для аутентификации, бэкенда, веб-приложения и приложения для администраторов.
- Рабочее развёртывание в AWS: входящий в репозиторий стек CDK развёртывает описанную архитектуру AWS и подключает её публичные домены через Cloudflare.
Docker Compose не предназначен для рабочего развёртывания одной командой. Рабочий вариант привязан к AWS, и проект не заявляет о независимости инфраструктуры от поставщика.
Что сейчас входит в репозиторий
Это больше, чем отдельный редактор карточек. Сейчас репозиторий включает:
- веб-клиент на React и клиент для администраторов
- нативные клиенты для iOS на SwiftUI и для Android на Jetpack Compose
- локальное хранилище с приоритетом офлайн-работы и синхронизацию в пользовательских клиентах
- карточки с лицевой и обратной сторонами, теги, связанные медиафайлы и повторение по FSRS
- одноразовые коды по электронной почте без пароля через Amazon Cognito и сервис аутентификации
- чат с ИИ, работающий через развёрнутый асинхронный обработчик и предоставленные оператором данные доступа к моделям
- точку подключения MCP для совместимых клиентов ИИ
- Agent API для терминальных инструментов и других автоматизированных процессов
Актуальные границы сервисов лучше всего описаны в документации по архитектуре. В общедоступном руководстве по API описана точка входа в облачный Agent API.
Облачная и самостоятельная версии
| Область | Облачное приложение | Самостоятельное развёртывание |
|---|---|---|
| Первоначальная настройка | Откройте приложение и войдите | Настройте учётные записи, секреты и домены, затем разверните стек AWS |
| Инфраструктура | Управляется проектом Flashcards | Управляется вами в ваших учётных записях AWS и Cloudflare |
| База данных и резервные копии | Управляются за вас | Вы отвечаете за RDS, правила резервного копирования, миграции и восстановление |
| Аутентификация и электронная почта | Управляются за вас | Cognito, ваши данные доступа для отправки писем и DNS |
| ИИ | Использует конфигурацию облачного сервиса | Использует развёрнутый обработчик и ваши данные доступа к моделям; для гостевого доступа действует отдельная квота |
| Мониторинг | Выполняется за вас | CloudWatch/SNS и ваша конфигурация Sentry |
| Обновления | Выпускаются облачным сервисом | Вы получаете, проверяете, развёртываете и отслеживаете обновления |
| Стоимость | Действуют условия облачного тарифа | Вы напрямую оплачиваете AWS и услуги других поставщиков |
Самостоятельное развёртывание даёт вам контроль над установкой и базой данных. Вместе с тем вы отвечаете за обновления безопасности, секреты, доступность, резервное копирование, доставку электронной почты, мониторинг и расходы на облачные сервисы.
Требования и быстрый локальный запуск
Сейчас для локальной разработки нужны Git, Bash, GNU Make, Docker с Docker Compose, Node.js 24 и npm. Прилагаемый файл Compose запускает PostgreSQL 18.4 и применяет миграции базы данных.
Из корня репозитория:
git clone https://github.com/kirill-markin/flashcards-open-source-app.git
cd flashcards-open-source-app
cp .env.example .env
make db-up
npm install --prefix api
npm install --prefix apps/auth
npm install --prefix apps/backend
npm install --prefix apps/web
npm install --prefix apps/admin
Для самого короткого исключительно локального запуска запустите бэкенд с ролью, созданной миграцией, и явно включите небезопасную локальную аутентификацию:
AUTH_MODE=none \
ALLOW_INSECURE_LOCAL_AUTH=true \
DATABASE_URL=postgresql://backend_app:backend_app@localhost:5432/flashcards \
REPORTING_DATABASE_URL=postgresql://reporting_readonly:reporting_readonly@localhost:5432/flashcards \
make backend-dev
Затем запустите клиенты в отдельных терминалах:
make web-dev
make admin-dev
При этом сервис аутентификации Cognito намеренно не запускается. В руководстве по самостоятельному развёртыванию приведены отдельные URL баз данных и шаги загрузки переменных окружения для полного сценария с Cognito и make auth-dev. Веб-приложение работает по адресу http://localhost:3000, приложение для администраторов — по адресу http://localhost:3001, бэкенд — по адресу http://localhost:8080/v1, а аутентификация Cognito после настройки — по адресу http://localhost:8081.
Этот быстрый запуск охватывает разработку основного бэкенда, веб-приложения и приложения для администраторов. Chat V2 при этом недоступен: его маршруты не принимают транспорт AUTH_MODE=none, а локальные команды не запускают асинхронный обработчик чата.
Для рабочего развёртывания используйте предусмотренный в репозитории сценарий первого развёртывания, а не Docker Compose:
npm ci --prefix apps/auth
bash scripts/deploy/first-deploy.sh \
--region eu-central-1 \
--domain example.com \
--alert-email alerts@example.com
При работе с чистой копией сейчас нужно явно установить пакет аутентификации: вспомогательный скрипт развёртывания включает этот пакет в сборку, но не устанавливает его зависимости. Затем скрипт создаёт и обновляет реальные облачные ресурсы. Перед запуском прочитайте руководство по развёртыванию бэкенда и веб-приложений и руководство по развёртыванию AWS CDK.
Перенос данных полезен, но намеренно ограничен
Импорт и экспорт пакетов Flashcards охватывают карточки, их теги и связанные медиафайлы. Они не переносят историю повторений, состояние планировщика FSRS, настройки рабочего пространства, полные структуры колод или данные учётной записи.
Это различие важно при переходе между облачным сервисом и собственным развёртыванием. Переносимый пакет служит для передачи содержимого, а не для полной миграции базы данных или учётной записи. Для полноценной рабочей резервной копии оператор самостоятельно развёрнутой системы должен также управлять базой данных PostgreSQL и хранилищем медиафайлов, созданными стеком AWS.
ИИ и данные доступа к внешним сервисам
В исходный код не входят учётные записи облачных сервисов, средства на использование моделей или рабочие данные доступа. Оператор самостоятельно развёрнутой системы предоставляет необходимую конфигурацию:
- данные доступа AWS и учётную запись AWS для стека CDK
- домен и данные доступа Cloudflare для описанной настройки DNS
- данные доступа Resend для доставки электронной почты
- конфигурацию Sentry для обязательного мониторинга бэкенда
- необязательные данные доступа OpenAI и Langfuse для ИИ и трассировки
- конфигурацию GitHub для входящего в репозиторий процесса развёртывания
В развёртывании AWS функции ИИ необязательны. Стек CDK развёртывает асинхронный обработчик чата, а данные доступа к моделям разрешают поддерживаемые аутентифицированные запросы к ИИ. Переменная GUEST_AI_WEIGHTED_MONTHLY_TOKEN_CAP отдельно управляет использованием ИИ гостями; это не общий переключатель для ИИ у вошедших пользователей и пользователей с аутентификацией по bearer-токену. Если вы подключите MCP или другой внешний клиент ИИ, данные карточек, включённые в запрос, могут обрабатываться внешним поставщиком по его собственным условиям. Самостоятельное размещение базы данных не удерживает такие запросы внутри вашей инфраструктуры.
Честные ограничения бета-версии и эксплуатации
Flashcards всё ещё находится на раннем этапе развития. Репозиторий активно меняется, миграции и конфигурация развёртывания могут обновляться, а самостоятельное развёртывание предполагает, что вы умеете эксплуатировать приложение в AWS.
Стек CDK включает резервное копирование, оповещения, секреты и автоматизацию развёртывания, однако эти компоненты всё равно требуют оператора. Будьте готовы:
- проверять изменения инфраструктуры перед развёртыванием
- отслеживать выпуски и проверки общедоступных точек подключения
- подтверждать подписки на оповещения и DNS домена электронной почты
- защищать и регулярно заменять данные доступа
- проверять восстановление и планировать расходы на AWS
- отдельно собирать и распространять нативные мобильные приложения, если вы хотите выпускать собственные версии
Если такая эксплуатационная работа вам не нужна, облачное приложение будет проще.
Краткое сравнение с Anki и Quizlet
Anki — зрелый проект с открытым исходным кодом, большой экосистемой и развитыми сценариями работы на компьютере. Quizlet — управляемый пользовательский сервис, для начала работы с которым почти ничего не нужно настраивать. Каждый из них может оказаться правильным выбором в зависимости от того, что для вас важнее: проверенный локальный инструмент или полностью управляемая платформа.
Flashcards идёт другим путём: это открытый репозиторий веб-приложений, мобильных клиентов, API и инфраструктуры, построенных вокруг FSRS, синхронизации, сценариев работы с ИИ, MCP и возможности самостоятельного развёртывания в AWS. Проект моложе Anki и при самостоятельном развёртывании требует значительно больше эксплуатационной работы, чем Quizlet. Выбирать его стоит тогда, когда такое сочетание соответствует вашим потребностям, а не потому, что каждый учащийся должен управлять облачным стеком.
Попробуйте облачное приложение или разверните собственный стек
- Открыть облачное приложение
- Прочитать руководство по самостоятельному развёртыванию
- Посмотреть исходный код на GitHub
Используйте облачную версию, если хотите учиться, не занимаясь инфраструктурой. Выбирайте самостоятельное развёртывание, если контроль над установкой стоит работы с AWS, DNS, электронной почтой, мониторингом и обновлениями.