feat: add file-based admin settings panel at /admin (#866)

* feat: add file-based admin settings panel at /admin

Settings saved in the panel are written to data/settings.json and
overlaid onto process.env, taking precedence over environment
variables and applying immediately without restart. Enable by setting
ADMIN_PASSWORD; on serverless platforms without persistent disk the
panel degrades to read-only.

* polish: admin panel UI improvements

- Provider logos in credential rows (shared ProviderLogo component,
  extracted from model-config-dialog)
- Scroll-spy active state in the sidebar nav
- Green success state in the save bar that clears after a few seconds
- Wider content column (max-w-6xl) for less wasted space on desktop

* polish: admin panel section toggles and reorder

- Move Quota & Rate Limits to the end of the settings page
- Add enable switches to Observability and Quota sections; default off
  with fields grayed out, auto-on when any field is already configured

* polish: make section enable switch more visible

Wrap the switch in a labeled pill ('Enabled'/'Disabled') with border
and background so the off state is clearly visible.

* refactor: derive admin registry from PROVIDER_INFO, simplify page state

- Provider options, labels, and base-URL placeholders now come from
  PROVIDER_INFO instead of hand-copied lists (fixes SiliconFlow .com/.cn
  placeholder drift; panel names now match the model-config dialog)
- Replace free-text subgroup strings + SUBGROUP_PROVIDERS reverse map
  with a typed provider field on SettingDef
- Precompute SETTINGS_BY_GROUP and PROVIDER_SUBGROUPS at module level
- Merge justSaved into saveMessage, drop unused mainRef, hoist
  fetchSettings out of the component, dedupe savedText logic
- Serialize from SETTINGS_REGISTRY directly; json validators in a map
  instead of a hardcoded key check
- Make allowPrivateUrls a function so ALLOW_PRIVATE_URLS edits in the
  admin panel apply without restart

* feat: graphical model management in admin panel

Replace the provider credential fields and raw AI_MODELS_CONFIG JSON
textarea with a Models section mirroring the in-app model settings UI:
provider instance list with logos, credential fields per provider type,
model add/remove with suggestions, per-model connectivity test, and a
default-provider star.

On save the server derives everything the runtime needs into
settings.json: credential env vars (with _2 suffixes for multiple
instances of one provider), AI_MODELS_CONFIG, and AI_PROVIDER/AI_MODEL
for the default. Secrets round-trip as masked markers and are never
sent back to the browser. The general settings registry now only
covers non-provider settings (generation, access, features,
observability, quota).

* fix: allow testing unsaved providers in admin panel

The test button previously looked up credentials by providerId in the
saved settings, so testing a newly added (unsaved) provider failed with
'Unknown provider or model'. The test endpoint now accepts the client's
current provider state; newly typed secrets are used as-is and masked
markers are resolved against the stored values, so testing works both
before and after saving.

* fix: merge env AI_MODELS_CONFIG with admin panel providers

Previously, saving in the admin panel wrote a complete AI_MODELS_CONFIG
into settings.json, which (by overlay precedence) replaced any config
from .env or ai-models.json — admins lost their env-configured models.

The panel no longer writes AI_MODELS_CONFIG. Instead its providers are
merged with the env baseline at read time in loadRawServerModelsConfig,
and panel credentials go to ADMIN_-prefixed env vars wired up via
apiKeyEnv/baseUrlEnv so they never shadow standard vars. Env-based
providers now appear read-only in the panel, name clashes are rejected,
and a panel default overrides the env default. data/ is now gitignored.

* fix: block global-credential providers already managed via env

Bedrock, Vertex AI, and Ollama credentials live in fixed env vars with
no apiKeyEnv redirection, so a panel instance of one of these would
silently override the credentials that env-configured models rely on.
The API now rejects saving such a provider when the env config already
uses that type, and the Add Provider dropdown disables it with a
'managed via env' note.

* fix: address admin panel review findings

- Security: test-model no longer resolves a stored secret when the
  request's baseUrl/provider differs from the stored entry, closing a
  path where a tampered baseUrl could exfiltrate a saved key
- Save failures are now visible: the save bar shows the error in red
  (was masked by the persistent 'Unsaved changes' text), and per-field
  validation errors from the settings API are surfaced under each field
- The Observability/Quota enable switch is now real: toggling off stages
  deletion of the group's saved values, and the toggle no longer snaps
  back to Enabled after saving
- Env provider's default star is hidden when a panel provider is the
  active default (no more double star)
- Clearing a credential field reverts to the stored value instead of
  silently deleting it; an explicit X button removes a stored secret
- Form inputs are disabled during an in-flight save

* refactor(admin): split 1549-line admin page into focused modules

Extract admin-shared.ts (types + fetch helper), setting-field.tsx
(registry-driven fields), and models-section.tsx (provider/model
manager) from page.tsx. Pure mechanical move, no behavior change.

* feat(admin): share credential fields with user dialog and localize panel

Extract ProviderCredentialsFields (display name + per-provider
credential inputs) used by both the user ModelConfigDialog and the
admin Models panel; secret input passed via renderSecret (plaintext
vs masked), test button via footer slot. Add full i18n for the admin
panel across en/zh/ja/zh-Hant, reusing modelConfig.* for shared parts.

* fix(admin): address Copilot review findings

- Reflect built-in defaults for boolean settings (ALLOW_PRIVATE_URLS
  defaults on) and allow clearing a saved boolean back to default,
  so the SSRF toggle matches actual runtime behavior.
- Harden JSON loading: filter settings values to strings only, and
  schema-validate stored ADMIN_PROVIDERS entries, dropping malformed
  ones instead of letting them reach runtime code.
- Set beforeunload returnValue so the unsaved-changes prompt shows in
  all browsers; reject non-finite numbers in settings validation.
- Fix README/CN/JA docs that claimed the panel auto-generates
  AI_MODELS_CONFIG (providers are merged at read time, not written).
- Add unit tests for corrupted-file value filtering and provider
  schema validation.

* docs: move admin panel details to dedicated docs/{en,cn,ja}/admin-panel.md

The READMEs now carry a short blurb + link, matching the existing
per-topic docs (docker.md, ai-providers.md, ...). Removes the ~22-line
inline section and the duplicated data/settings.json mentions.

* fix(admin): address follow-up Copilot findings on the prior fixes

- loadAdminProviders now validates against a stored-shape schema where
  secrets are plain strings, so a hand-edited ADMIN_PROVIDERS holding an
  {isSet} marker is dropped instead of later crashing maskSecret().
- loadSettings guards against array values (typeof [] === 'object'),
  which would otherwise overlay numeric keys onto process.env.
- Admin SecretInput uses the bare id so the shared component's
  <Label htmlFor> stays associated (only one ProviderDetail mounts).
- Add tests: marker-secret rejection, array-values guard, bedrock
  multi-secret round-trip.
This commit is contained in:
Dayuan Jiang
2026-06-15 00:40:35 +09:00
committed by GitHub
parent 54ff8d982c
commit 449e4c4e26
37 changed files with 4343 additions and 725 deletions

View File

@@ -0,0 +1,398 @@
import fs from "fs"
import os from "os"
import path from "path"
import { afterEach, beforeEach, describe, expect, it } from "vitest"
import {
ADMIN_PROVIDERS_KEY,
adminProvidersToConfig,
deriveEnvUpdates,
loadAdminProviders,
maskAdminProviders,
mergeSecrets,
type StoredAdminProvider,
validateAdminProviders,
} from "@/lib/admin/providers"
import { _resetForTests, saveSettings } from "@/lib/admin/settings"
import { loadRawServerModelsConfig } from "@/lib/server-model-config"
let tmpDir: string
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "admin-providers-"))
process.env.SETTINGS_FILE = path.join(tmpDir, "settings.json")
_resetForTests()
})
afterEach(() => {
_resetForTests()
delete process.env.SETTINGS_FILE
delete process.env.AI_MODELS_CONFIG
fs.rmSync(tmpDir, { recursive: true, force: true })
})
function provider(
overrides: Partial<StoredAdminProvider> = {},
): StoredAdminProvider {
return {
id: "p1",
provider: "openai",
apiKey: "sk-test",
models: ["gpt-5.2"],
...overrides,
}
}
describe("deriveEnvUpdates", () => {
it("writes credentials to ADMIN_-prefixed env vars (never shadows standard vars)", () => {
const updates = deriveEnvUpdates([provider()], [])
expect(updates.ADMIN_OPENAI_API_KEY).toBe("sk-test")
expect(updates.OPENAI_API_KEY).toBeUndefined()
expect(JSON.parse(updates.ADMIN_PROVIDERS as string)).toHaveLength(1)
// AI_MODELS_CONFIG is no longer written (merged at read time)
expect(updates.AI_MODELS_CONFIG).toBeNull()
})
it("suffixes env vars for a second instance of the same provider", () => {
const updates = deriveEnvUpdates(
[
provider({ id: "p1", name: "First" }),
provider({
id: "p2",
name: "Second",
apiKey: "sk-second",
models: ["gpt-5-mini"],
}),
],
[],
)
expect(updates.ADMIN_OPENAI_API_KEY).toBe("sk-test")
expect(updates.ADMIN_OPENAI_API_KEY_2).toBe("sk-second")
})
it("maps bedrock credentials to AWS env vars", () => {
const updates = deriveEnvUpdates(
[
provider({
provider: "bedrock",
apiKey: undefined,
awsAccessKeyId: "AKIA123",
awsSecretAccessKey: "secret",
awsRegion: "us-west-2",
models: ["claude-x"],
}),
],
[],
)
expect(updates.AWS_ACCESS_KEY_ID).toBe("AKIA123")
expect(updates.AWS_SECRET_ACCESS_KEY).toBe("secret")
expect(updates.AWS_REGION).toBe("us-west-2")
})
it("clears keys owned by the previous list when providers are removed", () => {
const prev = [provider()]
const updates = deriveEnvUpdates([], prev)
expect(updates.ADMIN_OPENAI_API_KEY).toBeNull()
expect(updates.AI_MODELS_CONFIG).toBeNull()
expect(updates.ADMIN_PROVIDERS).toBeNull()
})
it("sets AI_PROVIDER/AI_MODEL only when a default is flagged", () => {
const noDefault = deriveEnvUpdates([provider()], [])
expect(noDefault.AI_PROVIDER).toBeNull()
expect(noDefault.AI_MODEL).toBeNull()
const updates = deriveEnvUpdates(
[
provider({ id: "p1" }),
provider({
id: "p2",
provider: "deepseek",
models: ["deepseek-chat"],
isDefault: true,
}),
],
[],
)
expect(updates.AI_PROVIDER).toBe("deepseek")
expect(updates.AI_MODEL).toBe("deepseek-chat")
})
})
describe("adminProvidersToConfig", () => {
it("builds a config with ADMIN_-prefixed apiKeyEnv wiring", () => {
const config = adminProvidersToConfig([provider()])
expect(config.providers).toHaveLength(1)
expect(config.providers[0].models).toEqual(["gpt-5.2"])
expect(config.providers[0].apiKeyEnv).toBe("ADMIN_OPENAI_API_KEY")
})
it("wires suffixed env vars for a second instance", () => {
const config = adminProvidersToConfig([
provider({ id: "p1", name: "First" }),
provider({
id: "p2",
name: "Second",
apiKey: "sk-second",
models: ["gpt-5-mini"],
}),
])
expect(config.providers[1].apiKeyEnv).toBe("ADMIN_OPENAI_API_KEY_2")
})
it("skips providers without models and carries the default flag", () => {
const config = adminProvidersToConfig([
provider({ id: "p1", models: [] }),
provider({ id: "p2", name: "D", isDefault: true }),
])
expect(config.providers).toHaveLength(1)
expect(config.providers[0].default).toBe(true)
})
})
describe("mergeSecrets", () => {
it("keeps stored secret when client sends an isSet marker", () => {
const stored = [provider({ apiKey: "sk-original" })]
const merged = mergeSecrets(
[
{
...provider(),
apiKey: { isSet: true, hint: "…test" },
},
],
stored,
)
expect(merged[0].apiKey).toBe("sk-original")
})
it("replaces secret when client sends a plaintext string", () => {
const stored = [provider({ apiKey: "sk-original" })]
const merged = mergeSecrets(
[{ ...provider(), apiKey: "sk-new" }],
stored,
)
expect(merged[0].apiKey).toBe("sk-new")
})
it("clears secret when client sends undefined", () => {
const stored = [provider({ apiKey: "sk-original" })]
const merged = mergeSecrets(
[{ ...provider(), apiKey: undefined }],
stored,
)
expect(merged[0].apiKey).toBeUndefined()
})
})
describe("loadRawServerModelsConfig merge", () => {
it("combines env AI_MODELS_CONFIG with panel providers", async () => {
process.env.AI_MODELS_CONFIG = JSON.stringify({
providers: [
{
name: "Env OpenAI",
provider: "openai",
models: ["gpt-from-env"],
default: true,
},
],
})
saveSettings(deriveEnvUpdates([provider({ name: "Panel" })], []))
const merged = await loadRawServerModelsConfig()
expect(merged?.providers.map((p) => p.name)).toEqual([
"Env OpenAI",
"Panel",
])
// Env default kept because panel set none
expect(merged?.providers[0].default).toBe(true)
})
it("panel default overrides the env default", async () => {
process.env.AI_MODELS_CONFIG = JSON.stringify({
providers: [
{
name: "Env OpenAI",
provider: "openai",
models: ["gpt-from-env"],
default: true,
},
],
})
saveSettings(
deriveEnvUpdates(
[provider({ name: "Panel", isDefault: true })],
[],
),
)
const merged = await loadRawServerModelsConfig()
expect(merged?.providers[0].default).toBeFalsy()
expect(merged?.providers[1].default).toBe(true)
})
it("returns only env config when the panel has no providers", async () => {
process.env.AI_MODELS_CONFIG = JSON.stringify({
providers: [
{
name: "Env Only",
provider: "openai",
models: ["gpt-from-env"],
},
],
})
const merged = await loadRawServerModelsConfig()
expect(merged?.providers.map((p) => p.name)).toEqual(["Env Only"])
})
})
describe("validateAdminProviders", () => {
it("rejects names clashing with env-configured providers", () => {
expect(
validateAdminProviders([provider({ name: "Env OpenAI" })], {
providers: [
{
name: "Env OpenAI",
provider: "openai",
models: ["gpt-x"],
},
],
}),
).toMatch(/already defined/)
})
it("rejects a global-credential provider already in the env config", () => {
expect(
validateAdminProviders(
[
provider({
provider: "bedrock",
apiKey: undefined,
awsAccessKeyId: "AKIA-panel",
awsSecretAccessKey: "panel-secret",
awsRegion: "us-east-1",
models: ["claude-x"],
}),
],
{
providers: [
{
name: "Env Bedrock",
provider: "bedrock",
models: ["claude-env"],
},
],
},
),
).toMatch(/shares global credentials/)
})
it("allows a normal provider type alongside the same env type", () => {
expect(
validateAdminProviders([provider({ name: "Panel OpenAI" })], {
providers: [
{
name: "Env OpenAI",
provider: "openai",
models: ["gpt-x"],
},
],
}),
).toBeNull()
})
it("rejects two bedrock instances", () => {
const list = [
provider({ id: "p1", provider: "bedrock" }),
provider({ id: "p2", provider: "bedrock" }),
]
expect(validateAdminProviders(list)).toMatch(/Only one/)
})
it("rejects duplicate display names", () => {
const list = [
provider({ id: "p1", name: "Same" }),
provider({ id: "p2", name: "Same" }),
]
expect(validateAdminProviders(list)).toMatch(/unique/)
})
it("rejects multiple defaults", () => {
const list = [
provider({ id: "p1", isDefault: true }),
provider({ id: "p2", name: "Other", isDefault: true }),
]
expect(validateAdminProviders(list)).toMatch(/default/)
})
it("accepts a valid list", () => {
const list = [
provider({ id: "p1", isDefault: true }),
provider({ id: "p2", name: "Backup" }),
]
expect(validateAdminProviders(list)).toBeNull()
})
})
describe("loadAdminProviders", () => {
it("returns [] when nothing is stored", () => {
expect(loadAdminProviders()).toEqual([])
})
it("loads valid stored providers", () => {
saveSettings({ [ADMIN_PROVIDERS_KEY]: JSON.stringify([provider()]) })
expect(loadAdminProviders()).toHaveLength(1)
})
it("round-trips a bedrock provider with multiple string secrets", () => {
const bedrock = provider({
provider: "bedrock",
apiKey: undefined,
awsAccessKeyId: "AKIA123",
awsSecretAccessKey: "secret",
awsRegion: "us-west-2",
models: ["claude-x"],
})
saveSettings({ [ADMIN_PROVIDERS_KEY]: JSON.stringify([bedrock]) })
const loaded = loadAdminProviders()
expect(loaded).toHaveLength(1)
expect(loaded[0].awsAccessKeyId).toBe("AKIA123")
expect(loaded[0].awsSecretAccessKey).toBe("secret")
})
it("drops malformed entries and keeps valid ones", () => {
saveSettings({
[ADMIN_PROVIDERS_KEY]: JSON.stringify([
provider({ id: "good" }),
{ id: "missing-fields" }, // no provider/models
{ provider: "openai", models: ["x"] }, // no id
"not-an-object",
]),
})
const loaded = loadAdminProviders()
expect(loaded).toHaveLength(1)
expect(loaded[0].id).toBe("good")
})
it("returns [] when the stored value is not an array", () => {
saveSettings({ [ADMIN_PROVIDERS_KEY]: JSON.stringify({ nope: true }) })
expect(loadAdminProviders()).toEqual([])
})
it("returns [] on invalid JSON", () => {
saveSettings({ [ADMIN_PROVIDERS_KEY]: "{ broken" })
expect(loadAdminProviders()).toEqual([])
})
it("drops entries whose secret is an {isSet} marker, not a string", () => {
// A hand-edited file could hold a transit-only marker object; if it
// slipped through, maskSecret() would throw on a non-string value.
saveSettings({
[ADMIN_PROVIDERS_KEY]: JSON.stringify([
{ ...provider(), apiKey: { isSet: true, hint: "…1234" } },
]),
})
const loaded = loadAdminProviders()
expect(loaded).toEqual([])
// Masking the loaded list must not throw
expect(() => maskAdminProviders(loaded)).not.toThrow()
})
})

View File

@@ -0,0 +1,158 @@
import fs from "fs"
import os from "os"
import path from "path"
import { afterEach, beforeEach, describe, expect, it } from "vitest"
import {
_resetForTests,
applyToEnv,
getEnvFallback,
getValueSource,
isSettingsWritable,
loadSettings,
saveSettings,
} from "@/lib/admin/settings"
let tmpDir: string
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "admin-settings-"))
process.env.SETTINGS_FILE = path.join(tmpDir, "settings.json")
_resetForTests()
})
afterEach(() => {
_resetForTests()
delete process.env.SETTINGS_FILE
fs.rmSync(tmpDir, { recursive: true, force: true })
delete process.env.TEST_ADMIN_VAR
})
describe("loadSettings", () => {
it("returns empty object when file does not exist", () => {
expect(loadSettings()).toEqual({})
})
it("reads values from the settings file", () => {
fs.writeFileSync(
process.env.SETTINGS_FILE!,
JSON.stringify({ version: 1, values: { TEST_ADMIN_VAR: "abc" } }),
)
expect(loadSettings()).toEqual({ TEST_ADMIN_VAR: "abc" })
})
it("drops non-string values from a corrupted file", () => {
fs.writeFileSync(
process.env.SETTINGS_FILE!,
JSON.stringify({
version: 1,
values: {
GOOD: "ok",
NUM: 5,
OBJ: { nested: true },
ARR: [1, 2],
NULL: null,
},
}),
)
expect(loadSettings()).toEqual({ GOOD: "ok" })
})
it("returns empty object when values is null", () => {
fs.writeFileSync(
process.env.SETTINGS_FILE!,
JSON.stringify({ version: 1, values: null }),
)
expect(loadSettings()).toEqual({})
})
it("returns empty object when values is an array (no numeric keys)", () => {
fs.writeFileSync(
process.env.SETTINGS_FILE!,
JSON.stringify({ version: 1, values: ["a", "b"] }),
)
// Without the Array.isArray guard this would yield { "0": "a", ... }
expect(loadSettings()).toEqual({})
})
})
describe("applyToEnv / saveSettings", () => {
it("overlays file values onto process.env", () => {
saveSettings({ TEST_ADMIN_VAR: "from-file" })
expect(process.env.TEST_ADMIN_VAR).toBe("from-file")
})
it("file value wins over pre-existing env value", () => {
process.env.TEST_ADMIN_VAR = "from-env"
saveSettings({ TEST_ADMIN_VAR: "from-file" })
expect(process.env.TEST_ADMIN_VAR).toBe("from-file")
})
it("deleting a key restores the original env value", () => {
process.env.TEST_ADMIN_VAR = "from-env"
saveSettings({ TEST_ADMIN_VAR: "from-file" })
saveSettings({ TEST_ADMIN_VAR: null })
expect(process.env.TEST_ADMIN_VAR).toBe("from-env")
})
it("deleting a key unsets env when there was no original value", () => {
saveSettings({ TEST_ADMIN_VAR: "from-file" })
saveSettings({ TEST_ADMIN_VAR: null })
expect(process.env.TEST_ADMIN_VAR).toBeUndefined()
})
it("persists across cache reset (file round-trip)", () => {
saveSettings({ TEST_ADMIN_VAR: "persisted" })
_resetForTests()
applyToEnv()
expect(process.env.TEST_ADMIN_VAR).toBe("persisted")
})
})
describe("getValueSource / getEnvFallback", () => {
it("reports file source when key is in settings", () => {
saveSettings({ TEST_ADMIN_VAR: "x" })
expect(getValueSource("TEST_ADMIN_VAR")).toBe("file")
})
it("reports env source when only env is set", () => {
process.env.TEST_ADMIN_VAR = "from-env"
applyToEnv()
expect(getValueSource("TEST_ADMIN_VAR")).toBe("env")
})
it("reports default when neither is set", () => {
expect(getValueSource("TEST_ADMIN_VAR")).toBe("default")
})
it("returns the shadowed env value as fallback", () => {
process.env.TEST_ADMIN_VAR = "from-env"
saveSettings({ TEST_ADMIN_VAR: "from-file" })
expect(getEnvFallback("TEST_ADMIN_VAR")).toBe("from-env")
})
})
describe("isSettingsWritable", () => {
it("returns true for a writable temp dir", () => {
expect(isSettingsWritable()).toBe(true)
})
it("returns false for an unwritable path", () => {
_resetForTests()
process.env.SETTINGS_FILE = "/nonexistent-root-dir/settings.json"
expect(isSettingsWritable()).toBe(false)
})
})
describe("settings file on disk", () => {
it("writes valid JSON with restrictive permissions", () => {
saveSettings({ TEST_ADMIN_VAR: "secret" })
const filePath = process.env.SETTINGS_FILE!
const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"))
expect(parsed).toEqual({
version: 1,
values: { TEST_ADMIN_VAR: "secret" },
})
const mode = fs.statSync(filePath).mode & 0o777
expect(mode).toBe(0o600)
})
})

View File

@@ -1,4 +1,5 @@
import { afterEach, describe, expect, it } from "vitest"
import { afterEach, beforeEach, describe, expect, it } from "vitest"
import { _resetForTests } from "@/lib/admin/settings"
import {
loadFlattenedServerModels,
type ServerModelsConfig,
@@ -7,11 +8,20 @@ import {
const ORIGINAL_ENV = { ...process.env }
beforeEach(() => {
// Isolate from any local data/settings.json (admin panel providers
// are merged into the server models config)
process.env.SETTINGS_FILE = "/nonexistent/settings.json"
_resetForTests()
})
afterEach(() => {
_resetForTests()
process.env.AI_PROVIDER = ORIGINAL_ENV.AI_PROVIDER
process.env.AI_MODEL = ORIGINAL_ENV.AI_MODEL
process.env.AI_MODELS_CONFIG_PATH = ORIGINAL_ENV.AI_MODELS_CONFIG_PATH
process.env.AI_MODELS_CONFIG = ORIGINAL_ENV.AI_MODELS_CONFIG
delete process.env.SETTINGS_FILE
})
describe("ServerModelsConfigSchema", () => {