Securo生产部署完全指南：Docker Compose与Kubernetes Helm Chart两种方式任选

Securo生产部署完全指南：Docker Compose与Kubernetes Helm Chart两种方式任选

【免费下载链接】securoOpen-source personal finance manager. Self-hosted, privacy-first.项目地址: https://gitcode.com/gh_mirrors/se/securo

Securo 是一款开源、自托管、隐私优先的个人财务管理工具，支持多账户管理、银行同步、自动分类规则、预算与储蓄目标等能力。本文是 Securo 生产部署完全指南，将带你通过Docker Compose或Kubernetes Helm Chart两种方式，把它安全地部署到自有服务器上，数据完全掌握在自己手中。

两种部署方式怎么选 🧭

先给结论，方便你快速决策：

对比项	Docker Compose	Kubernetes + Helm
适用场景	单机、家庭服务器、小团队	已有 K8s 集群、多节点、企业级
门槛	只需 Docker	需要 K8s 1.25+ 与 Helm 3.2+
弹性伸缩	手动	支持 HPA 自动扩缩容
数据库/Redis	内置容器，开箱即用	可内置，也可对接外部实例
存储	命名卷，简单	PVC，多节点需 RWX 存储

💡 个人和小型团队用Docker Compose足够；如果你已经在跑 Kubernetes，直接上Helm Chart，它自带健康探针、迁移 Job 和持久化配置。

部署前准备：环境与依赖

无论选哪种方式，先确认服务器满足以下基础条件：

• Linux 服务器（推荐 2 核 4G 内存起步）
• Docker（含 Compose 插件）或 Kubectl + Helm
• 一个可访问的域名（用于 HTTPS 反向代理，WebAuthn 通行密钥要求）
• 已克隆代码仓库：

git clone https://gitcode.com/gh_mirrors/se/securo cd securo

Securo 的技术栈由 FastAPI 后端、React 前端、PostgreSQL（含 pgvector 扩展）和 Redis + Celery 异步队列组成，这些在两种方案中都已被封装好，你无需手动搭建。

方式一：Docker Compose 生产部署

仓库内置两套 Compose 文件，生产部署使用预构建镜像的 docker-compose.prod.yml（开发用的docker-compose.yml会本地构建源码并开启热重载，不要用于生产）：

文件	用途
docker-compose.yml	开发环境，本地构建 + 热重载
docker-compose.prod.yml	生产环境，拉取官方镜像

第一步：生成 .env 配置文件

生产部署的核心是.env文件。最关键的变量是SECRET_KEY（会话签名密钥，必须改成随机值）：

openssl rand -hex 32 # 复制输出结果填入 SECRET_KEY

创建.env文件，最小可用配置如下：

SECRET_KEY=上面生成的64位随机字符串 FRONTEND_URL=https://securo.你的域名.com BACKEND_PORT=8000 FRONTEND_PORT=3000

几点说明：

• DEBUG在 docker-compose.prod.yml 中默认已设为false，无需再改；
• FRONTEND_URL必须与用户实际访问的域名一致，它同时影响 CORS、OAuth 回调地址和 WebAuthn 通行密钥注册；
• 文件内置健康检查与depends_on依赖顺序：数据库和 Redis 就绪后才会启动后端，后端启动时会自动执行alembic upgrade head完成数据库迁移。

第二步：一键启动

docker compose -f docker-compose.prod.yml pull docker compose -f docker-compose.prod.yml up -d

生产栈会拉起以下服务：

服务	说明
db	PostgreSQL 16 + pgvector 扩展
redis	队列与缓存
backend	FastAPI 后端（含自动迁移）
frontend	nginx 托管的 React 前端（对外端口 3000）
celery-worker	异步任务（银行同步、定期交易、汇率更新）
celery-beat	定时任务调度器

第三步：验证健康状态

后端暴露/api/health接口，一行命令即可确认：

curl http://localhost:8000/api/health

官方还提供了一个安装脚本 install.sh，它会自动检测操作系统与容器运行时、生成随机SECRET_KEY、拉取镜像并等待健康检查通过，适合 Linux/macOS 快速体验。

可选增强：按需开启银行同步与 OIDC 登录

所有可选功能都通过.env变量开启，重启即生效：

• 巴西银行同步：配置PLUGGY_CLIENT_ID/PLUGGY_CLIENT_SECRET
• 欧洲 PSD2 银行：配置ENABLE_BANKING_APP_ID等变量
• 美国及国际银行（SimpleFIN）：SIMPLEFIN_ENABLED=true
• OIDC 单点登录（如 Pocket ID）：配置OIDC_ENABLED=true及OIDC_CLIENT_ID、OIDC_DISCOVERY_URL等；若只允许 SSO 登录，再设置LOCAL_AUTH_ENABLED=false

更多银行对接细节见 README.md 的 "Bank Sync" 章节。

方式二：Kubernetes Helm Chart 部署

官方 Helm Chart 位于 charts/securo/，当前版本 0.16.1（见 Chart.yaml），部署内容包括前端、后端、Celery Worker、Beat 调度器、PostgreSQL、Redis 及迁移 Job，全部带资源限额与健康探针。

第一步：前置检查

• Kubernetes 1.25+、Helm 3.2+
• 集群具备动态 PV 供应能力（附件文件需要持久卷）

第二步：从仓库直接安装

克隆代码后即可本地安装，无需额外仓库源：

helm install securo ./charts/securo -n securo --create-namespace

安装完成后 Chart 会打印访问指引（NOTES.txt），未配置 Ingress 时可以用端口转发先体验：

kubectl -n securo port-forward svc/securo-frontend 8080:3000 # 浏览器打开 http://127.0.0.1:8080

第三步：关键配置项

所有配置集中在 charts/securo/values.yaml，最常用的几项：

配置项	说明
global.domain	应用对外域名，如securo.example.com
global.tls	是否通过 HTTPS 访问（影响生成的链接）
secret.secretKey	会话密钥，生产必须修改
global.existingSecret	推荐：指向已有 K8s Secret 管理敏感信息
persistence.attachments.accessMode	附件卷访问模式，多节点集群需改为ReadWriteMany
ingress.enabled/httpRoute.enabled	启用 Ingress 或 Gateway API 路由
postgresql.enabled/redis.enabled	设为false可对接外部数据库与 Redis
autoscaling.enabled	开启 CPU 利用率驱动的 HPA 自动扩缩容

多节点存储的关键提醒 ⚠️

后端、Celery Worker 与 MCP Server 会同时挂载同一个附件卷。如果你的 Pod 可能调度到不同节点，必须使用支持ReadWriteMany（RWX）的 StorageClass（如 NFS、CephFS）；只有单节点部署才能用默认的ReadWriteOnce。详见 charts/securo/README.md。

生产 Secret 最佳实践

不建议把明文密钥写进values.yaml。先手动创建 Secret，再引用它：

kubectl -n securo create secret generic securo-secrets \ --from-literal=secretKey=$(openssl rand -hex 32)

global: existingSecret: "securo-secrets"

Secret 需包含secretKey、databaseUrl等键。卸载应用时执行helm uninstall securo，PVC 会被保留以避免误删数据，需手动清理。

部署后的第一件事：创建账户并体验核心功能

浏览器打开http://服务器IP:3000（或你的域名），完成首个管理员账户创建，即可进入仪表盘查看净资产、收支与目标进度。接下来建议：

1. 在Accounts中添加银行账户，手动录入或导入（OFX、QIF、CAMT、CSV）交易；
2. 在Rules页面配置自动分类规则——它支持一键导出/导入，换机迁移规则非常方便；
3. 在 Admin Settings 中设置应用时区，确保预算与定期交易按正确的零点切换。

常见坑位清单 ✅

问题	解决方案
访问页面报 CORS / 回调失败	FRONTEND_URL未与实际域名一致
通行密钥（Passkey）无法注册	必须使用 HTTPS 域名或 localhost；纯 IP/HTTP 不被 WebAuthn 标准允许
Pod 无法多节点调度、附件 404	存储未用 RWX，或 Pod 分散挂载了 RWO 卷
忘记改SECRET_KEY	生产务必替换默认开发值，重新生成后旧会话会失效
想开 AI Agents 功能	.env中设AGENTS_ENABLED=true，Compose 下用--profile agents启动

总结

Securo 为你提供了两条成熟的生产部署路径：Docker Compose三步起步，适合单机与家庭服务器；Helm Chart一次安装，适合 Kubernetes 集群环境，自带探针、迁移 Job、HPA 与持久化编排。两种方式的环境变量语义一致（Compose 的.env与 Chart 的config:/secret:一一对应），未来从单机迁移到集群几乎没有心智成本。数据在你自己的服务器上，隐私与掌控感，正是 Securo 自托管的核心价值。

【免费下载链接】securoOpen-source personal finance manager. Self-hosted, privacy-first.项目地址: https://gitcode.com/gh_mirrors/se/securo