Fuclaude 项目使用指南

核心功能解析

核心组件功能解析

Fuclaude 项目由四个核心文件构成，共同支撑项目的完整运行周期。这些组件如同精密仪器的关键部件，各自承担着不可或缺的角色。

📌 新手友好提示：所有核心文件需放置在同一目录下，修改配置后需重启服务使变更生效。

LICENSE 文件

采用 MIT 许可证（一种宽松的开源协议），允许用户自由使用、复制、修改和分发软件，只需保留原始版权声明。这意味着你可以将 Fuclaude 用于商业项目，也可以根据需求进行二次开发。

README.md 文件

项目的"身份证"，包含项目名称"Fuclaude"及简要描述。虽然当前内容简洁，但通常此类文件会包含项目简介、功能特点、使用方法等关键信息，是快速了解项目的入口。

config.json 文件

项目的"控制面板"，以 JSON 格式存储运行时参数。它就像设备的设置界面，允许你自定义端口、API 密钥等关键配置，无需修改源代码即可调整系统行为。

docker-compose.yml 文件

Docker 编排配置文件，用于定义和管理多容器应用。它相当于一份详细的"部署说明书"，告诉 Docker 如何拉取镜像、映射端口、设置环境变量，让应用部署过程标准化、自动化。

环境部署指南

三步部署指南

使用 Docker 部署 Fuclaude 项目仅需三个简单步骤，即使是 Docker 新手也能轻松完成。

🔧 步骤一：准备环境 首先确保你的系统已安装 Docker 和 Docker Compose。这就像在使用软件前需要先安装必要的运行环境一样。如果尚未安装，可以参考 Docker 官方文档进行安装。

🔧 步骤二：获取项目代码 打开终端，执行以下命令克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/fu/fuclaude

这一步会将项目的所有文件下载到你的本地计算机。

🔧 步骤三：启动服务 进入项目目录并启动服务：

cd fuclaude
docker-compose up -d

docker-compose up -d 命令会根据 docker-compose.yml 文件的配置，在后台启动 Fuclaude 服务。

验证方法

服务启动后，你可以通过以下方法验证部署是否成功：

1. 执行 docker-compose ps 命令，查看服务状态是否为 "Up"
2. 打开浏览器访问 http://127.0.0.1:8181，如果能看到项目界面则表示部署成功

⚠️ 常见问题：如果访问失败，可能是端口被占用。可以通过 netstat -tuln 命令查看端口占用情况，然后修改配置文件中的端口后重新启动。

配置参数详解

核心配置

Fuclaude 的配置体系采用"双轨制"，既可以通过 config.json 文件配置，也可以通过 docker-compose.yml 中的环境变量进行设置（环境变量优先级更高）。以下是关键配置项的详细说明：

配置项	默认值	推荐值	说明
bind / FUCLAUDE_BIND	127.0.0.1:8181	0.0.0.0:8181	服务绑定地址，0.0.0.0 表示允许外部访问
timeout / FUCLAUDE_TIMEOUT	600	300	请求超时时间（秒），推荐缩短以提高响应效率
openai_api_key / FUCLAUDE_OPENAI_API_KEY	sk-xxx	你的实际 API 密钥	OpenAI API 密钥，需替换为有效值才能使用相关功能
signup_enabled / FUCLAUDE_SIGNUP_ENABLED	false	false	是否允许新用户注册，生产环境建议关闭

网络配置

• bind: 服务绑定的 IP 地址和端口。Docker 环境下建议设为 0.0.0.0:8181，以便容器外部访问。
• proxy_url: 代理服务器地址，如需要通过代理访问外部服务可在此配置。

⚠️ 端口冲突解决方案：如果 8181 端口已被占用，可修改为其他未占用端口，如 127.0.0.1:8282，同时需同步修改 docker-compose.yml 中的端口映射。

安全配置

• site_password: 网站访问密码，设置后访问时需要输入密码验证。
• cookie_secret: Cookie 加密密钥，建议使用随机生成的 32 位字符串，提高安全性。
• real_logout: 是否真正登出，设为 true 时会清除所有会话信息。

📌 重要注意事项：cookie_secret 和 openai_api_key 属于敏感信息，不要提交到代码仓库或分享给他人。

扩展配置

对于有特殊需求的用户，可以考虑以下高级配置：

内容审核

• moderation_enabled: 是否启用内容审核功能
• moderation_model: 审核模型名称，默认使用 "omni-moderation-latest"

时区设置

在 docker-compose.yml 中通过 TZ=Asia/Shanghai 设置时区，确保日志时间与本地时间一致。

个性化配置方案

根据不同使用场景，推荐以下配置组合：

开发环境：

{
  "bind": "0.0.0.0:8181",
  "signup_enabled": true,
  "moderation_enabled": false
}

生产环境：

{
  "bind": "0.0.0.0:8181",
  "site_password": "your_strong_password",
  "signup_enabled": false,
  "moderation_enabled": true,
  "cookie_secret": "your_random_32_char_secret"
}

📌 新手友好提示：修改配置后，需执行 docker-compose down && docker-compose up -d 重启服务使配置生效。