# Firefly-Admin-Console **Repository Path**: L3thargy/firefly-admin-console ## Basic Information - **Project Name**: Firefly-Admin-Console - **Description**: Firefly 博客的开源管理后台。可视化编辑文章、相册与配置,Git 提交和推送由你确认后执行;支持一键本地运行、自动安装 Node/Git,也可打包上传服务器。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-13 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Firefly Admin Console 面向 [Firefly](https://github.com/CuteLeaf/Firefly) 博客的开源管理后台。直接读写博客仓库中的 Markdown、配置与图片文件,Git 提交与推送始终由你确认后执行。 ## 功能 - **文章管理**:新建、编辑、发布/转草稿、置顶、标签与分类、加密文章、批量操作 - **内容模块**:动态、相册、媒体库、单页、项目展示、友链、音乐、主页图片 - **配置中心**:结构化表单与源码(TS/JSON)编辑,直接修改博客仓库配置文件 - **发布流程**:查看 Diff、选择性提交、撤销变更、回滚提交、同步与推送到远程 - **初始化向导**:首次启动选择本地仓库文件夹;空文件夹可填远程地址与 HTTPS 访问令牌完成克隆 - **安全**:单管理员、scrypt 密码哈希、会话签名、CSRF 校验、操作审计日志 - **界面**:Firefly 文档站风格,响应式列表(窄屏自动切换卡片),支持深色模式 ## 技术栈 | 层 | 技术 | | --- | --- | | 前端 | Vue 3.5、TypeScript、Vite 8、Element Plus 2、CodeMirror 6、Vditor | | 后端 | Node.js 22+、Fastify 5、Zod 4、sharp、ts-morph、yaml | | 仓库 | Git(通过子进程调用,不依赖前端 Git 服务) | ## 目录结构 ``` firefly-admin/ ├── server/ # Fastify API 服务 │ └── src/ │ ├── routes/ # 接口路由 │ ├── services/ # Git、内容、配置、初始化等业务逻辑 │ └── store/ # 账号、项目配置、操作日志 ├── web/ # Vue 3 管理界面(base 为 /admin/) ├── scripts/ # 冒烟测试等辅助脚本 ├── local-blog/ # 默认博客仓库目录(仅保留 .gitkeep) ├── .env.example # 环境变量示例 └── package.json # npm workspaces 根配置 ``` ## 运行与部署 两种方式任选其一,都需要 Node.js 22+ 与 Git。 ### 方式一:本地一键运行 Windows 双击 `start.bat`;Linux / macOS 执行 `./start.sh`。 脚本会自动检查环境、安装依赖、首次构建,并启动服务后打开 `http://127.0.0.1:5175/admin/`。之后的启动会直接使用已有 `dist`。 - 关闭窗口或按 `Ctrl+C` 即停止服务 - 如果 `5175` 端口已被占用(例如另一个实例或开发服务在运行),脚本会直接提示端口冲突并退出,不会静默结束 - 首次运行需要联网安装依赖;`node_modules` 缺失或关键依赖不完整时会自动执行 `npm install` - 未安装 Node.js 22+、Node.js 版本过低或缺少 npm 时,脚本会询问是否从镜像站自动安装;按顺序尝试 npmmirror、华为云、清华、官方源,并校验 SHA256,安装到项目下 `.runtime/node`,不改动系统环境 - 未安装 Git 时会询问是否自动安装:Windows 从 npmmirror 下载 PortableGit 解压到 `.runtime/git`,Linux / macOS 使用系统包管理器(apt / dnf / yum / apk / pacman);跳过或安装失败只会警告,Git 相关功能不可用 - 依赖安装或构建失败时,窗口会保留错误信息,可按提示手动执行 `npm install` / `npm run build` ### 方式二:构建部署包(上传服务器) Windows 双击 `build-upload.bat`;Linux / macOS 执行 `./build-upload.sh`。 脚本会自动检查 Node.js 22+ 与 npm、补齐缺失依赖,构建前端与后端,并在 `release/` 下生成: - `firefly-admin-/`:可直接复制到服务器的部署目录 - `firefly-admin-.zip`:可在宝塔「文件」里直接上传解压 部署包只包含运行时文件: - `web/dist`、`server/dist` - 运行时 `package.json`(服务端生产依赖)与启动脚本 `start.sh` / `start.bat` - `README.md`、`LICENSE`、`.env.example` - `local-blog/.gitkeep` 把 zip 上传到服务器解压,首次执行 `start.sh`(Windows 为 `start.bat`)会自动安装生产依赖并启动,无需在服务器上构建前端。脚本同样会检测 Node.js 22+ 与 Git,缺失时提示自动安装。 也可以直接使用 npm 命令:`npm run build:upload` 生成目录与 zip,`npm run build:release` 只生成目录。 ### 开发模式 ```bash npm install npm run dev # 前端 5174,后端 5175 ``` 打开 `http://127.0.0.1:5174/admin/`。 首次启动会自动创建管理员账号,初始密码保存在 `server/data/initial-credentials.txt`: - 用户名:`admin` - 初始密码:`FireflyAdmin2026` 首次登录会强制修改账号与密码,修改成功后初始凭据文件自动删除。 登录后进入初始化向导: 1. 填写博客仓库的**本地绝对路径**(默认 `firefly-admin/local-blog`) 2. 文件夹为空时,填写远程仓库地址;私有仓库需填写 HTTPS 访问令牌(仅用于本次克隆,不会保存) 3. 文件夹已是 Git 仓库时直接使用 4. 确认分支、远程名与提交身份后完成初始化 ## 环境变量 后台根目录下的 `.env` 会自动加载,已存在的系统环境变量优先。 | 变量 | 默认值 | 说明 | | --- | --- | --- | | `HOST` | `127.0.0.1` | 服务监听地址,容器内为 `0.0.0.0` | | `PORT` | `5175` | 服务端口 | | `BLOG_REPO_PATH` | `local-blog` | 博客仓库路径,相对路径按后台根目录解析 | | `DATA_DIR` | `./data` | 账号、项目配置、操作日志等数据目录 | | `GIT_BIN` | `git` | Git 可执行文件路径,Windows 可填绝对路径 | | `SESSION_SECRET` | 开发用默认值 | 会话签名密钥,生产环境必须替换 | | `COOKIE_SECURE` | 生产环境为 `true` | 直接 HTTP 部署时设为 `false` | | `NODE_ENV` | `development` | 生产部署设为 `production` | ## 生产部署建议 - 服务本身即可托管 `/admin/` 页面与 `/api/`,只需暴露 5175 端口 - 如需 HTTPS,可在前面增加 Nginx 反向代理 - 必须设置强随机 `SESSION_SECRET` - 不要提交或公开 `data/`、`.env` 与 `local-blog/` 中的博客仓库内容 ## 说明 - `local-blog/` 仅通过 `.gitkeep` 保留空目录,克隆的博客内容会被 `.gitignore` 忽略 - 访问令牌保存在后台数据目录 `data/git-credential.json`(权限 `0600`),用于克隆以及后续 HTTPS 拉取/推送;仅在执行 Git 命令时临时注入,不写入博客仓库配置或日志,可在「发布 → 项目设置」中更换或清除 - 本后台直接操作博客仓库文件,建议在测试仓库验证后再用于线上仓库 ## License [MIT](./LICENSE)