Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

fix(backups): bound the automatic dump pile (#1675) (#1679)

tashdroid9e3f314c4c61
diff --git a/.env.example b/.env.example
index 56d15c58..fb9f207b 100644
--- a/.env.example
+++ b/.env.example
@@ -358,6 +358,12 @@ REQUEST_ANALYTICS_MAX_ROWS=100000
# FREEAPI_DB_BACKUP_KEY=use-a-separate-64-char-hex-key-or-omit-to-use-ENCRYPTION_KEY
# FREEAPI_DB_BACKUP_INTERVAL_MS=300000
+# Automatic dump files on the Backups page (#1675): how many dumps created by
+# the scheduler or the desktop updater's pre-update snapshot to keep. Older
+# ones are deleted (file + row) on the next dump write. Manual and pre-restore
+# dumps are never auto-deleted. 0 keeps every auto dump (disables the prune).
+# AUTO_BACKUP_DUMP_RETENTION=10
+
# Optional declarative startup config. Use either inline JSON or a path to a JSON
# file. It is applied idempotently after migrations on every boot — before the
# HTTP listener starts, so an "admin" entry closes the first-run setup window
diff --git a/docs/en/env/01-variables.md b/docs/en/env/01-variables.md
index 6777d534..59d9ad9c 100644
--- a/docs/en/env/01-variables.md
+++ b/docs/en/env/01-variables.md
@@ -132,6 +132,7 @@ In Docker, `127.0.0.1` is the container, not your machine — see [03-outbound-p
| `FREEAPI_DB_BACKUP_TOKEN` | Unset | Optional bearer token for uploads to `FREEAPI_DB_BACKUP_URL`. |
| `FREEAPI_DB_BACKUP_KEY` | Uses `ENCRYPTION_KEY` if omitted | Separate 64-char hex key for the backup envelope. |
| `FREEAPI_DB_BACKUP_INTERVAL_MS` | `300000` (5 min) | Period between background backups. |
+| `AUTO_BACKUP_DUMP_RETENTION` | `10` | Count bound for the automatic dump files on the Backups page (#1675): keeps the newest N dumps whose source is `scheduled` or `pre-update`, deleting the older files and their rows on the next dump write. Manual and pre-restore dumps are never auto-deleted. `0` disables the prune (keeps every auto dump forever). |
| `FREEAPI_CONFIG_PATH` | Unset | Optional declarative startup config: path to a JSON file applied idempotently after migrations on every boot. Example: `/app/server/data/freellmapi.config.json`. |
| `FREEAPI_CONFIG_JSON` | Unset | Same declarative config inline instead of via file, e.g. `{"keys":[{"platform":"groq","key":"gsk_...","label":"main"}],"routing":{"strategy":"balanced"}}`. |
| `FREELLMAPI_UPDATE_CHECK` | Enabled | Manual application update checker. Set to `off` to hide it from Settings and prevent Git discovery or outbound update-check requests. This also switches off the automatic release reminder, which is a separate dashboard setting (Settings > General) that stays off until turned on there. |
diff --git a/docs/zh-cn/env/01-variables.md b/docs/zh-cn/env/01-variables.md
index cdfefea5..22b29be1 100644
--- a/docs/zh-cn/env/01-variables.md
+++ b/docs/zh-cn/env/01-variables.md
@@ -118,6 +118,7 @@ FreeLLMAPI 从 `.env` 读取的全部变量,按主题分组。默认值和说
| `FREEAPI_DB_BACKUP_TOKEN` | 未设置 | 向 `FREEAPI_DB_BACKUP_URL` 上传时可选的 bearer 令牌。 |
| `FREEAPI_DB_BACKUP_KEY` | 省略时使用 `ENCRYPTION_KEY` | 备份信封专用的 64 位十六进制密钥,可与主密钥分开。 |
| `FREEAPI_DB_BACKUP_INTERVAL_MS` | `300000`(5 分钟) | 后台备份之间的间隔。 |
+| `AUTO_BACKUP_DUMP_RETENTION` | `10` | Backups 页面自动转储文件的数量上限(#1675):保留来源为 `scheduled` 或 `pre-update` 的最新 N 个转储,在下次写入转储时删除更早的文件及其记录。手动与 pre-restore 转储永不被自动删除。`0` 表示禁用清理(永久保留所有自动转储)。 |
| `FREEAPI_CONFIG_PATH` | 未设置 | 可选的声明式启动配置:指向一个 JSON 文件的路径,每次启动都会在迁移之后幂等地应用。示例:`/app/server/data/freellmapi.config.json`。 |
| `FREEAPI_CONFIG_JSON` | 未设置 | 同样的声明式配置,以内联方式而非文件给出,例如 `{"keys":[{"platform":"groq","key":"gsk_...","label":"main"}],"routing":{"strategy":"balanced"}}`。 |
| `FREELLMAPI_UPDATE_CHECK` | 启用 | 手动的应用更新检查器。设为 `off` 可把它从设置页隐藏,并阻止 Git 发现和对外发出的更新检查请求。这也会一并关掉自动版本提醒——那是另一个独立的仪表盘设置项(设置 > 通用),在被打开之前始终保持关闭。 |
diff --git a/server/src/__tests__/services/backup-auto-retention.test.ts b/server/src/__tests__/services/backup-auto-retention.test.ts
new file mode 100644
index 00000000..0692d981
--- /dev/null
+++ b/server/src/__tests__/services/backup-auto-retention.test.ts
@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { initDb, getDb } from '../../db/index.js';
+import {
+ createBackup,
+ getAutoDumpRetention,
+ pruneAutoDumps,
+} from '../../services/backups.js';
+
+// #1675: automatic dumps (scheduled + the desktop updater's pre-update
+// snapshot) used to pile up forever. Manual and pre-restore dumps are never
+// auto-deleted.
+const ORIGINAL_KEEP = process.env.AUTO_BACKUP_DUMP_RETENTION;
+
+function restoreEnv() {
+ if (ORIGINAL_KEEP === undefined) delete process.env.AUTO_BACKUP_DUMP_RETENTION;
+ else process.env.AUTO_BACKUP_DUMP_RETENTION = ORIGINAL_KEEP;
+}
+
+function fileOf(id: number): string {
+ return (getDb().prepare('SELECT filepath FROM backups WHERE id = ?').get(id) as { filepath: string }).filepath;
+}
+
+describe('auto backup dump retention (#1675)', () => {
+ let dataDir = '';
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-autodump-'));
+ process.env.FREEAPI_DB_PATH = path.join(dataDir, 'freeapi.db');
+ initDb(':memory:');
+ });
+
+ afterAll(() => {
+ delete process.env.FREEAPI_DB_PATH;
+ restoreEnv();
+ });
+
+ beforeEach(() => {
+ getDb().prepare('DELETE FROM backups').run();
+ });
+
+ afterEach(restoreEnv);
+
+ it('defaults to keeping 10 auto dumps and honours valid env overrides', () => {
+ delete process.env.AUTO_BACKUP_DUMP_RETENTION;
+ expect(getAutoDumpRetention()).toBe(10);
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '3';
+ expect(getAutoDumpRetention()).toBe(3);
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '0';
+ expect(getAutoDumpRetention()).toBe(0);
+ process.env.AUTO_BACKUP_DUMP_RETENTION = 'nope';
+ expect(getAutoDumpRetention()).toBe(10);
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '-2';
+ expect(getAutoDumpRetention()).toBe(10);
+ });
+
+ it('prunes old scheduled/pre-update dumps and unlinks their files, keeping the newest', () => {
+ // Sweep disabled while writing, so all four dumps exist before the prune.
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '0';
+ const auto = [
+ createBackup(getDb(), { source: 'scheduled' }),
+ createBackup(getDb(), { source: 'pre-update' }),
+ createBackup(getDb(), { source: 'scheduled' }),
+ createBackup(getDb(), { source: 'pre-update' }),
+ ];
+ // 4 auto dumps, keep 2: the two newest survive, the two oldest go.
+ const paths = auto.map((b) => fileOf(b.id));
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '2';
+ const deleted = pruneAutoDumps(getDb());
+ expect(deleted).toBe(2);
+ const remaining = (getDb().prepare('SELECT id FROM backups ORDER BY id').all() as { id: number }[]).map((r) => r.id);
+ expect(remaining).toEqual([auto[2].id, auto[3].id]);
+ expect(fs.existsSync(paths[0])).toBe(false);
+ expect(fs.existsSync(paths[1])).toBe(false);
+ expect(fs.existsSync(paths[2])).toBe(true);
+ });
+
+ it('never deletes manual or pre-restore dumps', () => {
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '0';
+ const manual = createBackup(getDb(), { source: 'manual' });
+ const preRestore = createBackup(getDb(), { source: 'pre-restore' });
+ const scheduled = createBackup(getDb(), { source: 'scheduled' });
+ // Turn the knob on after the fact: the auto one is the only candidate.
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '0';
+ expect(pruneAutoDumps(getDb(), 0)).toBe(0);
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '5';
+ expect(pruneAutoDumps(getDb())).toBe(0); // only 1 auto dump, under the bound
+ expect(fs.existsSync(fileOf(manual.id))).toBe(true);
+ expect(fs.existsSync(fileOf(preRestore.id))).toBe(true);
+ // And a keep of 1 still spares both non-auto dumps while the single auto
+ // dump is the newest auto row.
+ const scheduledFile = fileOf(scheduled.id);
+ const second = createBackup(getDb(), { source: 'pre-update' });
+ expect(pruneAutoDumps(getDb(), 1)).toBe(1); // the older auto dump goes
+ const remaining = (getDb().prepare('SELECT id FROM backups ORDER BY id').all() as { id: number }[]).map((r) => r.id);
+ expect(remaining).toEqual([manual.id, preRestore.id, second.id]);
+ expect(fs.existsSync(scheduledFile)).toBe(false);
+ });
+
+ it('createBackup sweeps automatically once the bound is exceeded', () => {
+ process.env.AUTO_BACKUP_DUMP_RETENTION = '2';
+ const ids: number[] = [];
+ for (let i = 0; i < 5; i++) ids.push(createBackup(getDb(), { source: 'pre-update' }).id);
+ const remaining = (getDb().prepare('SELECT id FROM backups ORDER BY id').all() as { id: number }[]).map((r) => r.id);
+ expect(remaining).toEqual(ids.slice(3));
+ });
+});
diff --git a/server/src/services/backups.ts b/server/src/services/backups.ts
index 57142d3b..adf0d2f3 100644
--- a/server/src/services/backups.ts
+++ b/server/src/services/backups.ts
@@ -10,6 +10,25 @@ import type { Scheduler } from '../lib/scheduler.js';
const SCHEDULE_SETTING = 'backup_schedule';
const LAST_RUN_SETTING = 'backup_last_run_day';
+// #1675: the automatic dump sources — the background scheduler and the
+// desktop updater's pre-update snapshot — write a full dump each time they
+// fire and nothing ever removed one. A single-user desktop install that
+// updated a few times a month accumulated 60-70 MB per update indefinitely.
+// Manual dumps are the operator's own intent and pre-restore snapshots are
+// the only undo for a restore, so neither is ever auto-deleted; only the two
+// sources the software creates by itself are bounded, by count. `0` disables
+// the prune (the "documented opt-out" the issue asks for).
+const DEFAULT_AUTO_DUMP_RETENTION = 10;
+export const AUTO_DUMP_SOURCES: ReadonlySet<string> = new Set(['scheduled', 'pre-update']);
+
+export function getAutoDumpRetention(): number {
+ const raw = process.env.AUTO_BACKUP_DUMP_RETENTION;
+ if (raw === undefined || raw.trim() === '') return DEFAULT_AUTO_DUMP_RETENTION;
+ const parsed = Number(raw);
+ if (!Number.isInteger(parsed) || parsed < 0) return DEFAULT_AUTO_DUMP_RETENTION;
+ return parsed;
+}
+
/** Bumped whenever the on-disk dump layout changes in a way an older restore
* path would misread. Restore refuses anything it does not know. */
const DUMP_FORMAT = 1;
@@ -304,9 +323,60 @@ export function createBackup(
'INSERT INTO backups (filename, filepath, filesize, is_full, source, created_at, tables_json) VALUES (?, ?, ?, ?, ?, ?, ?)',
).run(filename, filepath, filesize, isFull ? 1 : 0, source, createdAt, JSON.stringify(tables));
+ // #1675: writing a dump is the one moment we know the auto-dump pile needs
+ // re-checking. Runs after the insert so the fresh row counts toward the
+ // bound, and never fails the backup that just succeeded.
+ try {
+ pruneAutoDumps(db);
+ } catch (err) {
+ console.error('[backups] auto-dump retention sweep failed:', err);
+ }
+
return { id: Number(result.lastInsertRowid), filename, filesize, isFull, source, createdAt, tables };
}
+/**
+ * Bound the pile of automatic dumps (#1675).
+ *
+ * The scheduler and the desktop updater append a full dump each and nothing
+ * removed them, so disk usage grew forever (the reporter's `backups/` held
+ * 60-70 MB per app update). Keeps the newest `AUTO_BACKUP_DUMP_RETENTION`
+ * auto dumps per source-agnostic count; `0` keeps every dump (opt-out).
+ * Manual and pre-restore dumps are never touched: one is operator intent,
+ * the other is the only undo for a restore.
+ *
+ * Deleting the row reuses deleteBackup's path re-check (a stale or hand-edited
+ * row may point outside the data directory; that dump is left alone rather
+ * than unlinking an arbitrary file) — so a dump whose file is already gone
+ * still loses its index row, which is the half that mattered for the listing.
+ */
+export function pruneAutoDumps(db: Db, keep = getAutoDumpRetention()): number {
+ if (keep <= 0) return 0;
+ const stale = db.prepare(`
+ SELECT id FROM backups
+ WHERE source IN (${[...AUTO_DUMP_SOURCES].map(() => '?').join(', ')})
+ AND id NOT IN (
+ SELECT id FROM backups
+ WHERE source IN (${[...AUTO_DUMP_SOURCES].map(() => '?').join(', ')})
+ ORDER BY created_at DESC, id DESC
+ LIMIT ?
+ )
+ ORDER BY id ASC
+ `).all(...AUTO_DUMP_SOURCES, ...AUTO_DUMP_SOURCES, keep) as { id: number }[];
+
+ let deleted = 0;
+ for (const row of stale) {
+ try {
+ deleteBackup(db, row.id);
+ deleted += 1;
+ } catch {
+ // Path outside the data directory (or row vanished mid-sweep): not ours
+ // to delete; the next sweep tries again, same as today's behaviour.
+ }
+ }
+ return deleted;
+}
+
/* ------------------------------------------------------------------ */
/* Backup listing / download / delete / restore */
/* ------------------------------------------------------------------ */